Email Pro

Email is a full mail client inside the admin. Connect your own mailboxes, then read, write, send, search and file mail, and hand messages and attachments over to the site.

What it does

• Reads any standard IMAP mailbox, with several mailboxes per person. Each person sees only their own.
• Sends through each mailbox's own outgoing (SMTP) server.
• Microsoft 365, Outlook.com and Gmail can be connected by signing in with Microsoft or Google instead of a password - no app password needed.
• Replies, forwards, drafts, attachments, Cc, Bcc, priority and read receipts.
• Star, mark read or unread, move, delete and mark as spam, one message or many.
• Create, rename, delete and hide folders.
• Search and conversations (threads) over folders it keeps a copy of.
• Identities with signatures, reusable templates, filing rules and an away message.
• Undo send, send later and snooze.
• Save an attachment to Media, turn a message into a draft page, or file it as a collection entry.
• Your emails with a contact, listed on their card in Contacts (needs MongoDB).
• An unread count on the Email sidebar item, for each mailbox's Inbox (needs MongoDB). It shows 0 when everything is read.

Unlike the free Mail Reader, Email changes things on the mail server just as any mail app does: opening a message marks it as read, and moves and deletes happen on the server.

Requirements

• Your mailbox details: the IMAP (incoming) and SMTP (outgoing) server names, ports, username and password. Your email provider publishes these. For Microsoft 365, Outlook.com or Gmail you can sign in with the provider instead - see Signing in with Microsoft or Google below.
• MongoDB, for part of the plugin. Email keeps a copy of the message list (sender, subject, date and flags, never the message text) of the folders you choose, so they open instantly and can be searched.

Without MongoDB, Email still loads. Reading, starring, moving, deleting, folders and sending straight away all work. These need MongoDB and show a message saying so when it is missing:

• Search
• Conversations
• Rules
• Undo send and send later
• Snooze
• The away message
• Choosing which folders to keep a copy of

On a managed site, the MongoDB Adapter plugin sets up the database connection. Anywhere else, whoever runs the site adds a MongoDB connection named default in the site's database connections.

Email replaces the free Mail Reader. While Email is enabled, Mail Reader is not loaded. Your saved mailboxes, passwords and trusted image senders carry across.

Getting started

1. Open Email from the admin sidebar.
2. Click Add a mailbox, or the cog at the top of the Folders pane (Mail account settings).
3. On the Mailboxes tab click Add mailbox and fill in Name, IMAP server, Port, Username, Password and Use TLS (port 993).
4. Click Test connection, then Save.
5. Open the Outgoing tab. Fill in Outgoing server, Port (587 for STARTTLS, 465 for implicit TLS), Implicit TLS (on for 465), Username (blank uses the incoming one), Password and From address.
6. Click Test connection on that tab. It saves the settings, then signs in with them.
7. Optional: on Identity set your display name and signature.
8. Close the panel. Click the pencil (New message) or press c to write.

Signing in with Microsoft or Google

Microsoft 365, Outlook.com and Gmail accounts can be connected by signing in with the provider, instead of typing a password. Nothing is typed into this site but your app's details, the provider can withdraw the sign-in at any time, and no app password is needed.

You register a small app of your own with Microsoft or Google first. That way your mail is read with your sign-in only, and nobody else's app is involved. The form shows these steps with this site's exact redirect URI and a Copy button. The site's address must start with https:// (Settings > General > Site URL): Microsoft and Google only return to https addresses.

Microsoft 365 and Outlook.com

1. Go to entra.microsoft.com (or the Azure portal) > App registrations > New registration.
2. Name it, for example "Domma Mail". Supported account types: Accounts in any organizational directory and personal Microsoft accounts, or this organizational directory only for one company's mailboxes. Redirect URI: platform Web, and paste the address from the form.
3. Copy the Application (client) ID from the Overview.
4. Certificates & secrets > New client secret. Copy its Value (not the Secret ID) straight away - it is shown once. Note when it expires.
5. API permissions > Add a permission > Microsoft Graph > Delegated: tick IMAP.AccessAsUser.All, SMTP.Send, offline_access, openid and email.
6. Microsoft 365: the mailbox needs IMAP and Authenticated SMTP switched on (Microsoft 365 admin center > Users > the user > Mail > Manage email apps). Your organisation may also have to approve the app. Outlook.com: turn on IMAP under Settings > Mail > Forwarding and IMAP.
7. In Email, open Mail Settings > Mailboxes > Add mailbox and choose Sign in with Microsoft. Fill in Application (client) ID, Client secret and, for a single-organisation app, Tenant (its Directory (tenant) ID; otherwise leave common).
8. Click Connect with Microsoft and sign in as the mailbox in the window that opens. Allow pop-ups for the site if the browser blocks it.

For a Microsoft 365 shared mailbox, type its address in Email address and sign in as someone with Full Access to it.

Gmail and Google Workspace

1. Go to console.cloud.google.com and create a project. Under APIs & Services > Library enable the Gmail API.
2. Set up the OAuth consent screen (newer consoles: Google Auth Platform). Audience: Internal on Google Workspace. A personal Gmail account needs External.
3. Data access: add the scope https://mail.google.com/.
4. Publish the app (Audience > Publish app, In production). While an External app is in Testing, Google ends the sign-in after 7 days and the mailbox needs reconnecting every week.
5. Clients > Create client (or Credentials > OAuth client ID): type Web application. Under Authorised redirect URIs paste the address from the form.
6. In Email, Add mailbox > Sign in with Google. Fill in Client ID and Client secret, click Connect with Google and sign in as the mailbox.

Google calls https://mail.google.com/ a restricted scope. An app offered to the public needs Google's verification and a security assessment. An Internal Workspace app does not. For your own mailboxes (fewer than 100 users) you can skip verification and click through Google's "unverified app" warning (Advanced > Go to your app). On Google Workspace an administrator may have to allow the app (Admin console > Security > API controls).

After connecting

• The incoming and outgoing servers are the provider's, filled in for you. On Outgoing only the From address can be changed.
• The sign-in renews itself. If the provider refuses (you withdrew it, the client secret expired, or a Testing app reached 7 days), the mailbox shows Needs reconnecting, checking stops, and you get a notification. Open the mailbox under Mailboxes and click Reconnect. Leave Client secret blank to keep the saved one; type a new one if it expired.
• Test signs in to both servers. Disconnect forgets the sign-in but keeps the mailbox and its settings. Google is also told to cancel it. Microsoft has no way for an app to hand a sign-in back: to cut it off at Microsoft too, delete the app's client secret in Entra.
• An existing password mailbox can be moved onto a sign-in: Edit it and choose Sign in with Microsoft or Sign in with Google.

Screens

Folders

• Click a folder to open it. Tick Unread to show only folders with unread mail.
• The folder-plus button adds a folder.
• Right-click a folder for New folder, New folder inside (folder name), Show in the list or Hide from the list, Rename and Delete.
• Inbox and the special folders (Sent, Drafts, Trash, Junk and so on) cannot be renamed or deleted.
• Deleting a folder deletes every message in it, and every folder inside it. You are asked first.

Message list

• Search mail... searches the folders Email keeps a copy of. Type at least two characters. Clear goes back to the folder.
• The speech-bubble button groups messages into conversations.
• The clock button opens Waiting: mail waiting to be sent and snoozed mail (see below). A number shows how many are waiting.
• Refresh fetches the list again.
• Newer and Older page through the folder, 50 messages a page. The picker between them shows 25, 50, 100 or 200 a page instead; this browser remembers your choice, and changing it keeps you at the same messages. It applies to conversations and search results too.
• Drag a message onto a folder to move it. Dragging one of several selected messages moves them all.
• Reply and forward icons show which messages you have acted on. Hover over an icon to see Replied to or Forwarded. They appear after the message is sent successfully, including scheduled sends; saving a draft does not mark the original.

To select several messages, tick them, Ctrl-click, Shift-click or press x. The box at the top selects every message on this page. A bar then offers Mark read, Mark unread, Star, Spam or Not spam, Delete and Clear.

After a move, delete or spam action, a bar at the bottom offers Undo for a short time.

Message menu

Right-click a message for:

• Reply, Reply all, Forward (or Edit draft on a draft)
• Mark as read or Mark as unread
• Star or Unstar
• Add sender to contacts (when the Contacts Tool is on)
• Mark as spam or Not spam
• Snooze...
• Move to (your folder tree)
• Save to the site > As a draft page or As a collection entry...
• Delete

Delete moves the message to Trash. Deleting from Trash removes it from the server for good.

Reading a message

• Buttons above the message: Reply, Reply all, Forward, Snooze, and Unsubscribe when the sender offers one.
• Show headers reveals Reply-To, all recipients and the message id.
• Remote images are blocked. Load images loads them for this message; Always from (address) trusts that sender from now on.
• Click an attachment to download it. The picture-plus button beside it saves it to the Media library.
• Right-click the message itself (or press Shift+F10 or the menu key while reading it) for the same actions as the message menu, plus Copy and Quote in reply when you have selected some text. Quote in reply starts a reply that quotes only what you selected. Right-clicking a link or picture in the message gives your browser's own menu.

Unsubscribe: when the list supports one-click unsubscribe, Email does it for you. Otherwise it opens the list's unsubscribe page in a new tab, or opens a message for you to send.

Writing a message

The compose window has:

• From - shown when the mailbox has more than one identity. Changing it swaps the signature.
• To - separate addresses with commas. Start typing to pick from Contacts; picking a group adds all its members.
• Cc / Bcc reveals Cc, Bcc, Priority (Normal, High, Low) and Ask for a read receipt.
• Subject and Message.
• Insert a template... - when you have templates.
• Attach files - up to 20 MB in total. The running total turns red over the limit.
• Discard, Save draft, Later... and Send.

Later... offers In an hour, This evening, Tomorrow morning, This weekend, Next week, or Or pick a time. The message then waits in Waiting until its time.

With an undo delay set (see Sending), Send holds the message for that many seconds so you can take it back.

If you leave the screen with a changed message open, it is saved to Drafts.

Waiting

• Waiting to send: scheduled messages. Send now (or Try again if it failed) and Cancel. Cancel gives you the message back to edit.
• Snoozed: messages out of sight until their time. Bring back now returns one early.

Snooze

1. Choose Snooze... on a message.
2. Pick a quick choice, or Or pick a time and Use this time.

The message moves to a folder on the server (Snoozed by default), so your phone agrees it is out of the inbox. At the chosen time it moves back.

Saving to the site

Action	What it makes	Permission needed
Save an attachment to Media	A file in the Media library, renamed if the name is taken	Media: create
As a draft page	A draft page from the message text, without the quoted reply or signature. You are offered the page editor.	Pages: create
As a collection entry...	An entry in the collection you pick, with a preview of which part of the message goes in which field. Click File it.	Collections: create

Only images (JPG, PNG, GIF, WebP, ICO, BMP, TIFF), PDF, text, CSV and Word and Excel files can be saved to Media. SVG and HTML files never can.

On a contact's card

Open a contact in Contacts and the foot of the card lists Emails: the ten newest messages to or from any of the contact's addresses (the main email, the billing email and any more email addresses), beside their Bookings, Calls and Events. Each says Received or Sent, says unread when you have not read it, and names the mailbox when you have more than one. Select one to open it in Email.

Only your own mailboxes are searched, so two people looking at the same contact each see their own correspondence. The list covers the folders Email keeps a copy of (see Sync; Inbox and Sent by default) and needs MongoDB; without it the list is not shown.

Keyboard

Press ? for the list.

Key	Does
Up and Down, or j and k	Move through the list
Left and Right	Move between folders and messages
Enter	Open
u	Mark read or unread
s	Star or unstar
r / Shift-R (or a)	Reply / reply all
f	Forward
c	New message
/	Search
x	Select or deselect
Shift-A	Select all on this page
!	Mark as spam, or not spam
# or Delete	Delete
Esc	Clear search or selection

Settings

Click the cog in the Folders pane. Mail Settings has these tabs. Each tab applies to the mailbox you are looking at.

Mailboxes

Add, Edit and Remove mailboxes, with a password or by signing in with Microsoft or Google (see above). When editing, leave Password blank to keep the saved one. Passwords are stored encrypted and never sent back to the browser. A server on the site's own private network (a LAN or loopback address) is refused unless it is the site's own outgoing server or the site administrator has set allowPrivateMailHosts in the plugin's settings.

Images

Senders whose remote images always load, with Stop trusting. Offer to remember senders switches the list on or off without losing it.

Folders

Tick the folders Email keeps a copy of, then Save selection. Use default goes back to Inbox and Sent. Only these folders can be searched and grouped into conversations. Other folders are read straight from the server.

Import mail… (also beside New folder in the Folders pane, and on each folder's and mailbox's menu) brings in one .mbox file or up to 50 .eml files (25 MB, 1,000 messages at most). Choose an existing folder, or name a new one and where it goes. The messages are added to the mail server itself, with their original dates and read state. Importing the same file again skips messages already there; a message with no Message-ID cannot be checked, so it is added again.

Sync

How often the kept folders are checked for new mail: Default (5 min), 3, 5, 10 or 15 minutes. Sync now checks straight away. If checks keep failing, Email backs off automatically and shows the last error here.

Outgoing

The mailbox's SMTP server: see Getting started. A mailbox signed in with Microsoft or Google sends through the provider's server; only the From address can be changed. Test connection saves first, then signs in, so a failure names the real problem. The same private-network rule as for mailboxes applies, and Test connection can be used ten times a minute.

Identity

The names and addresses this mailbox sends as. The first identity is the default; use the arrows to reorder.

• Name for this identity, Display name, Send from, Reply-To.
• Signature, with When to add it: New messages, Replies, Forwards, and On replies and forwards (above the quoted message, or at the very bottom).
• Add identity and Remove, then Save.

Sending from another address only works if your mail provider allows this mailbox to send as it.

Templates

Text you send often. Each has a Name, a Subject and a body. A template is added above what is already in the message, and sets the subject only if it is empty.

Placeholders you can use:

{{to.name}}    The first recipient's name, or their address if it has none
{{to.first}}   The first recipient's first name
{{to.email}}   The first recipient's address
{{my.name}}    Your display name on this identity
{{my.email}}   The address this message sends from
{{subject}}    The message's subject, as it currently stands
{{date}}       Today's date
{{time}}       The time now

Anything else in double braces is left as written, so a typo shows up before you send.

Sending

• Hold for - the undo delay: Send immediately, 5, 10, 20 or 30 seconds. Default 10 seconds.
• Snoozed mail waits in - the folder name, Snoozed by default. It is created on the server when first needed.
• Where rules run - the folders rules act on. Inbox only by default.

Rules

Mail that files itself. Each rule has:

• When: Every condition below must hold or Any one condition is enough, then conditions. Add condition for more.
• Then: actions. Add action for more.

Conditions on	Tests
Sender, Recipient, Subject, Mailing list, Priority	contains, does not contain, is exactly, starts with, ends with, matches (use * as a wildcard)
Has an attachment	is true, is false
Size in KB	is more than, is less than

Actions: Move to folder, Copy to folder, Mark as read, Flag it, Treat as spam, Move to Trash, Stop processing further rules.

Click Test to see what a rule would catch in mail Email already holds, before you Save.

Rules only run on new mail arriving in the Where rules run folders, after rules were first saved. They never refile old mail. A rule with no conditions, or an empty condition, matches nothing.

Away

An automatic reply while you are away.

• Send an away message (on or off), Subject (default "Out of office"), From and Until (both optional), Tell the same person again after (1 to 30 days), Only answer people in my contacts, and the message itself.
• What would it answer? runs the real decision over your recent mail and gives the reason for each message. Nothing is sent.
• A list shows who has been answered.

It never answers automatic mail (including other away messages), mailing lists, bounces and no-reply addresses, mail you sent yourself, mail you were only Bcc'd on, or anyone already told within the period you set. Away replies are not saved in Sent.

The Outgoing tab must be set up first.

Diagnostics

Build, mailbox, folder and recent errors, with Copy diagnostics for a support request. Never shows passwords.

Notifications

Email tells only the mailbox's owner, in the admin notifications:

• "(mailbox) cannot be checked" - after 5 failed checks in a row. It clears itself when a check works again.
• "(mailbox) needs signing in again" - Microsoft or Google refused to renew the sign-in. It clears when you Reconnect.
• "A message could not be sent" - a scheduled or held message failed. Open Waiting to try again.

Permissions and roles

In System > Roles, Email uses the Email permission in the Plugins group, shared with Mail Reader:

Action	Label	Allows
email.read	Use	Add your own mailboxes, read and send mail

Only the admin role has it by default. Give Email > Use to other roles to let their members use their own mailboxes. Nobody can see anyone else's mailboxes.

Saving to the site also needs the site permission for what is created (Media, Pages or Collections), whatever the mailbox.

Tips

• Use the mail server's real name. If a test says "The mail server's TLS certificate could not be verified", the server name you typed probably does not match the server's certificate. Ask your provider for the exact host name their certificate covers and use that for both IMAP server and Outgoing server.
• "The mail server rejected that username and password": some providers need an app password. For Microsoft 365, Outlook.com and Gmail, signing in with the provider avoids it.
• Keep only the folders you search in the Folders tab. Large folders take several sync passes to catch up.
• A conversation that crosses a page boundary can show as two.

Limitations

• IMAP and SMTP only. Sign-in (instead of a password) is offered for Microsoft and Google only, with an app you register yourself.
• Without MongoDB, search, conversations, rules, undo send, send later, snooze and the away message are unavailable.
• Rules use simple wildcards (*), not regular expressions.
• Snooze needs a mail server that supports UIDPLUS; the server refuses otherwise.
• Mail connections are kept by the running site. The site must run as a single server process.