Accounts and aliases
A plMail account is one mailbox you have somewhere else — an IMAP server, Gmail, or Outlook — that plMail signs into and syncs. You can connect as many as you like; they sync independently and read as one inbox.
Everything on this page lives under Settings → Mail accounts, except where it says otherwise.
Adding an IMAP mailbox
Settings → Mail accounts → Add account, on the IMAP / SMTP tab. Enter the address and password. The Provider dropdown carries the settings for a long list of common providers and is matched against the domain you typed, so for most mailboxes the host, port and encryption fill themselves in; several entries also carry a note about something the provider requires, such as IMAP needing to be switched on in their web interface first. If yours is not listed, take the IMAP and SMTP details from your provider's documentation.
A blank form starts on port 993 with SSL for incoming and port 587 with STARTTLS for outgoing, which is what nearly every provider wants.
Test connection probes IMAP and SMTP separately and reports each. Saving does not depend on it, but an account that stores cleanly and cannot log in is the failure worth catching now rather than at the first sync, so the probe runs again on save and its outcome is remembered on the account.
The first sync starts immediately, and the account's existing mail is then brought in newest first: the most recent of the Inbox within a minute or so, the rest of the Inbox after it, then Sent, Drafts and your own folders, the archive, and Spam and the bin last. Mail that arrives while this runs is not held up by it. A chip beside the search box says Importing for as long as an account is, and opens a list with how much of each is in and which folder it is on; if nothing has moved for a while it says Waiting to continue, and an account that cannot be reached is listed under Account health.
After that, plMail holds an IMAP IDLE connection to each mailbox and syncs the moment something changes, with a scheduled sweep every fifteen minutes behind it.
See IMAP and SMTP for the settings servers disagree about.
Adding Gmail or Outlook
Both are OAuth, so an administrator has to register an application with the provider before the button does anything. Once that is done, Add account offers Continue with Google and Continue with Microsoft on the OAuth tab, and the whole flow is the provider's own consent screen — no password is stored here at all.
Grant everything the consent screen asks for. Google's screen lists the permissions as separate tick boxes and lets you decline any of them — and declining one does not fail the sign-in. The account connects, plMail says so, and the part you withheld quietly does not work: calendars that never sync, or mail where marking read and archiving appear to work on screen, are refused by Google, and are undone by the next sync. A Microsoft tenant can withhold the same permissions by policy.
plMail now compares what it was given against what it asked for and puts a card on Account health when they differ, with a button to connect again and grant the rest. If you connected an account before this existed, the card appears the first time the account refreshes its sign-in, or the first time a change is refused.
Microsoft accounts go through Graph rather than IMAP. That is deliberate: Exchange Online treats IMAP as legacy authentication and blocks it in any tenant running Security Defaults.
The registration itself — which console, which redirect URI, which scopes — is on
Google and Microsoft. Where the credentials
go is a choice: an administrator can enter them in Admin → Integrations under Mail sign-in,
or leave them in the environment as GOOGLE_OAUTH_* and MICROSOFT_OAUTH_*, which is what an
older installation will already be doing. See Administration.
An OAuth account has no editable form here. There is nothing to edit — no password, no host — so it is managed by connecting and disconnecting rather than by a settings page.
The account list
Accounts are listed in your own order and can be dragged to reorder. The order is cosmetic. It decides where a row sits and nothing else.
Which account a new message is composed from is a separate, stored choice: the primary account, marked Primary on its row and set by Make primary on any other. This used to be the same thing — the top row was the primary — which meant tidying the list silently changed the address you send from, with nothing on screen saying so. Two decisions, two controls.
The coloured dot beside each account is its identity colour: the same tone that account's messages wear in the unified lists, so two accounts can be told apart at a glance in a list that mixes them. It is handed out when the account is added — the first of eight colours not already in use — and from then on it changes only when you change it. Reordering the list does not repaint it, and it is not a status light. Whether an account is actually working is answered on Account health, which is the one place that claims to answer it.
You change it with the coloured swatch on the account's row, which opens the palette of eight. That control is on every account, Gmail and Outlook ones included, which is why it is not a field in Edit account: that form is closed to them. The sidebar dot changes at once, and every list you open afterwards wears the new colour on that account's messages; a list already open in another tab repaints when it reloads. Choosing a colour another account already wears is allowed, so two accounts can be made a pair.
Each row offers:
| Control | Effect |
|---|---|
| Colour swatch | Opens the palette; the colour you pick is the account's from then on — on any account |
| Make primary | Sends new messages from this account by default — on any row but the primary's |
| Disable account / Enable account | Stops or resumes syncing without deleting anything |
| Edit account | Server settings and password — password accounts only |
| Choose which folders to sync | Switches individual IMAP folders on or off — IMAP accounts only; see Folders to sync |
| Remove account | Deletes the account and every message synced from it |
The primary flag is never lost. Removing the account that held it hands it to another, and the very first account you add is primary because there is nothing for it to inherit from.
Removing an account deletes its synced mail from plMail's database and nothing at the provider. It also tries to tear down any push registration it had, so nothing is left pointing at an account that no longer exists.
Anything else that takes a registration away now hands it back to the provider the same way — deleting a calendar, unticking one, disconnecting a connection, and an administrator's data reset. The attempt is best-effort: a provider that refuses, that has already expired the channel, or that cannot be reached is stepped over rather than blocking the removal, because a reset that will not run because Google is unreachable is a worse outcome than a channel that lapses on its own within the week.
On the edit form, leaving the password field blank keeps the stored one.
Per-account settings
Three controls sit under each account row. Each re-renders on its own rather than reloading the whole list.
Instant delivery
Instant delivery switches an account between push and scheduled polling. It appears only for Gmail and Microsoft — a plain IMAP mailbox has no push manager, and IDLE already gives it the same effect.
Turning it on registers with the provider there and then. If registration fails the switch goes back off, so the interface never claims push is working while nothing is being delivered, and the reason is spelled out:
- Gmail — Google refused the watch. Check that
GMAIL_PUBSUB_TOPICnames a topic that exists and that the topic grantsgmail-api-push@system.gserviceaccount.comthe Pub/Sub Publisher role. Note the-push:gmail-api@system.gserviceaccount.comis not an address Google publishes from, so a topic granted exactly that will never deliver a single notification. - Microsoft — Microsoft could not reach this server over HTTPS. Check the reverse proxy and
APP_PUBLIC_URL.
Either way the account keeps syncing on a schedule. Push is an optimisation, never the only path.
The badge next to it reads Push when registrations are healthy, Scheduled when it is off, and one of two things when it is broken:
- Push (expired) — the registration's own expiry passed and nothing renewed it. Renewal runs daily on its own, so this usually means the scheduled-task worker has stopped.
- Push (not delivering) — the registration is alive and unexpired, and mail has arrived that it never announced. For Gmail that points at the Pub/Sub push subscription being missing or pointing somewhere else; for Microsoft, at a subscription that has lapsed.
Re-register push is the button for both, and Account health explains which of the two you are looking at and shows the dates it decided from.
Where push is not available on this server at all, the control says so rather than offering a switch that cannot work.
Sync labels to provider
Off by default. With it on, labels you create, rename or delete are mirrored to that provider, whether the change came from the web UI or from a JMAP client.
Only Gmail and Microsoft offer it. On plain IMAP a label is a physical folder, so creating and deleting labels would move real mail on the server — a different and riskier operation than the switch promises.
It only ever affects changes made from now on. Labels that already exist are not pushed retroactively, because that would mean bulk-creating your entire local tree at the provider from one click.
On Microsoft, most labels are Outlook categories rather than folders, and a category there has no identity but its name — the name is what is written onto each message. So renaming one does two things: the master category is renamed, and every message carrying the old name is pushed again so it carries the new one. That second half is the same question Outlook's own rename dialog asks; here it is answered yes, because the alternative is a mailbox where the label exists twice — once as a category and once as loose text on the mail that used to have it. A label on thousands of messages therefore means thousands of updates, sent in the background.
Labels that ARE backed by a real Exchange folder — the ones that came from one — are renamed as folders instead, and nothing has to be re-tagged.
Folders to sync
Choose which folders to sync opens the account's folders, each with a switch. Every folder starts on. Switching one off stops plMail fetching it: the mail already stored stays where it is, and switching the folder back on resumes from where it stopped. The inbox has no switch, because a client that has stopped fetching its inbox is not a client — to stop an account altogether, disable it.
Nested folders are indented under their parent. A folder that only groups others and holds no mail
of its own — Gmail's [Gmail], for one — is listed greyed out with its switch off and disabled:
the server will not open it, so there is nothing to fetch.
It appears only for IMAP accounts. A Gmail or Microsoft account syncs through its provider's API and has no folders to choose between. A folder the server has stopped listing is not shown.
Sending aliases
Settings → Aliases lists the addresses each account sends and receives as. Refresh from provider asks the account what it knows about; Add takes one you type yourself.
Each address is Primary, active, or disabled. The primary is the default sender for that account and cannot be disabled or removed — make another one primary first, which demotes it. Disabled addresses stay on the list and stop being offered in the compose window.
The From selector in the compose window lists accounts and aliases together, so sending as an alias is one choice rather than two.
A reply opens on the address the mail was sent to. Mail that came in for an alias is answered from that alias, without you picking it; mail that names none of the account's addresses — a list, a Bcc the server left no trace of — is answered from the primary one. Answering mail you sent yourself keeps the address you sent it from. The selector is still there to change it.
The name an address sends under
Under each address is a field for the sender name: what the recipient sees beside the address. Left empty, the address sends under the account's name, which is what the field shows greyed out. A family address on a personal account can be "Mr and Mrs Smith" while the account stays "John Smith". The From selector shows the same name the mail goes out with.
Catch-all domains
If your provider delivers every address at a domain to this mailbox, add the domain under
Catch-all domains. plMail then treats any address at that domain as yours for answering: a
reply to mail sent to anything@example.com goes out from anything@example.com, with the
account's name and signature, and you are left out of your own reply-all. A meeting invitation sent
to such an address is yours to answer, and the answer goes back from it. No alias has to be added
first, and nothing changes for mail that arrives.
Not every address at the domain is treated as you. A catch-all catches what has no mailbox of
its own, and on a family or company domain other people have one: anna@example.com is at your
catch-all domain and is somebody else. So an address counts as yours only for a mail it reached you
by — the address your server recorded delivering it to, or, where the server recorded none, the
addresses at that domain in To and Cc. Anna stays in your reply-all, her mail is answered to her
rather than as her, and an invitation naming her is not offered to you. Where a mail names both of
you and carries no delivery record, plMail cannot tell which was yours and treats both as you.
Three things it does not do. It is one domain exactly — example.com does not cover
mail.example.com. It applies to replies and forwards; a new message is still sent from an address
on the list above. And it is not offered for Gmail or Outlook accounts, which send only as addresses
the provider itself knows about and rewrite or refuse any other. plMail does not check that the
domain really is a catch-all, or that your provider lets you send from it: that is between you and
the provider, and a wrong entry shows up as a refused or rewritten sender on the first reply.
One caveat plMail states on the page itself: Outlook sends as the account's primary alias regardless of what you choose here. That is Microsoft's behaviour, changed in your Microsoft account settings, not here.
Gmail collecting mail for another account (Gmailify)
Gmail can fetch the mail of another address into your Gmail inbox. When that other address is connected here as well, every message reaches plMail twice: once through Gmail and once through the other account's own IMAP sync. plMail files such mail under the other account and merges the two copies into one, so a message is listed once. The merged message is still the other account's: its IMAP folder decides whether it is in the Inbox, the bin or another folder, whatever Gmail did with its own copy. Labels you give it in Gmail show here, and archiving, starring or labelling it here is also sent to Gmail.
Under each Gmail account on this page, File mail for my other accounts under them turns this on or off. It is on unless you turn it off. Turn it off once Gmail no longer collects that mail, typically after a domain has moved from Gmail to an IMAP provider of its own. Otherwise Gmail's old and late copies keep being matched to the other account. With it off:
- The Gmail account keeps only mail addressed to itself. Mail it has for other addresses is not stored again.
- The other account's own copies stop following Gmail. They lose the labels Gmail put on them, and a change you make to them is no longer sent to Gmail. The mail itself stays where its IMAP folder has it. This runs in the background, so on a mailbox that has collected mail for years it can take a few minutes after the switch is turned off.
- Mail that Gmail filed under the other account, and that the other account's IMAP server never had, stays as it is and keeps following Gmail. Gmail is the only place that mail exists.
Best turned off once Gmail has stopped collecting. While Gmail still collects the other address's mail, plMail tells that mail apart by its recipients: a message whose To or Cc names the other address, and not the Gmail address, is left to the other account, even though Gmail stamps its own address on it as the place it was delivered. A message Bcc'd to the other address names nobody, so it looks like the Gmail account's own mail and is kept on both accounts. Mailing lists and newsletters often arrive that way. Stop the collecting in Gmail (Settings → Accounts → Check mail from other accounts) and those duplicates stop too.
Turning it back on changes nothing that is already stored. Mail that arrives afterwards is matched again, and so is an older message once Gmail reports a change to it.
Mail moved by Gmail before v0.3.9. Earlier versions moved the other account's copy wherever Gmail moved its own. Mail trashed or archived in Gmail showed in plMail's bin or archive, although the IMAP server still had it in its Inbox. To put that mail back where its IMAP folder has it, an administrator runs:
php bin/console app:backfill gmailify-placement
Run it while the workers are quiet. A move you make in plMail updates the labels first and the IMAP folder a moment later, and a message caught in between would briefly go back to its old folder. Mail that those earlier versions removed because Gmail had emptied it from its bin is not brought back by this. The IMAP sync only fetches mail newer than what it already has.
What each address does by default
Two settings hang off the alias list rather than off the account, because they are properties of the address people see rather than of the mailbox it lives in.
Compose defaults, under the alias list on the same page, currently holds one control per address: what that address does when a sender asks to be told their mail was read. The default is Never send, and it is worth understanding before changing it — see Read receipts.
Settings → Signatures is its own section. The account has a signature, and any of its addresses can either inherit it, replace it, or deliberately sign with nothing. The three states and what the compose window does with them are in Composing.
Where to read further
- IMAP and SMTP, Google, Microsoft — the exact provider-side setup.
- Account health — what is broken, and the repairs that keep your mail.
- Mail ingest — what a sync run actually does.
- Configuration reference —
APP_PUBLIC_URL, the OAuth variables and the Pub/Sub ones. - Troubleshooting — when mail stops arriving.
Things that bite
Reordering the list no longer changes which account you send from. It used to, and an install upgraded from an older version keeps whichever account was first at the moment it upgraded. If Compose starts from the wrong address, the fix is Make primary on the right one — dragging it to the top will not do it.
A dead sign-in does not have to mean re-adding the account. Deleting a broken account and adding it again is the reflex, and it costs you every message synced from it. Settings → Account health offers a reconnect that keeps the mailbox; see Account health.
A large mailbox takes a while to arrive in full. plMail syncs everything the account holds; there is no setting that bounds it. The newest mail lands first, and the rest follows over the following runs, so an account added minutes ago is usable long before it is complete.
Testing the connection on an existing account needs a password in the field. A blank password means "keep the stored one" on the edit form, and the tester can only resolve that once the account id has reached it — otherwise it says so rather than testing with nothing.
Removing an account deletes its synced mail from plMail. Nothing is removed at the provider, and re-adding the account syncs it again from scratch.
A Google consent screen lets the user untick calendar access while allowing mail. The account connects, mail works, and no calendars appear. Reconnecting with the box left ticked is the fix.
Push failing is not an error state. A self-hosted install may have no publicly reachable HTTPS address at all. Registration failing means "stay on polling", and the fifteen-minute sweep is unaffected.
A message moved in another mail client into a folder that is switched off looks, to plMail, like one that left the account. The check that lets mail deleted elsewhere disappear from plMail only looks in the folders that are switched on, so a message filed elsewhere into a folder plMail is not fetching disappears here although it still exists on the server. That is the switch doing what it says, and nothing is lost: switch the folder on and plMail fetches the message again. A move made inside plMail is different — plMail knows where it put the message and keeps its copy.
This page is generated from docs/features/accounts.md. Edit it there — changes made here are overwritten on the next push to main.