Web administration interface
The web administration interface is the main website for maintaining your Mailu installation. For brevity the web administration interface will now be mentioned as admin gui. It offers the following configuration options:
change display name.
change the logged in user’s password.
change user defined spam filter tolerance.
configure automatic forwarding.
configure automatic email replies (out of office replies).
configure fetchmail for automatic email retrieval (from 3rd-party servers).
configure application passwords.
configure passkeys for signing in to the web interface.
send broadcast messages to all users.
configure global administration users.
configure relayed domains.
access Rspamd webui.
Configure all email domains served by Mailu, including:
generating dkim and dmarc keys for a domain.
view email domain information on how to configure your SPF, DMARC, DKIM and MX dns records for an email domain.
Add new email domains.
For existing domains, configure users, quotas, aliases, administrators and alternative domain names.
access the webmail site.
lookup settings for configuring your email client.
Access the web administration interface
The admin GUI is by default accessed via the URL https://<my domain>/admin, when it’s enabled in the setup utility
or by manually setting ADMIN=true in mailu.env.
Sign in with your email address and password, or use a registered passkey.
The sign-in page offers a destination selector for Webmail or Account settings.
A direct visit uses the destination from your last successful sign-in, remembered
in a separate browser cookie; that destination is pre-selected but can be changed
on the sign-in page. With no preference, Webmail is the default when enabled.
Bookmark /sso/login/admin or /sso/login/webmail to select a destination explicitly.
These routes also work with trusted proxy authentication and use the fixed /admin and /webmail paths. Protected-page links return you to the requested page after
sign-in, including after a required password change. All roles continue to open their
account settings when visiting /admin.
The admin GUI and sign-in page follow your system’s light or dark color scheme by default. Use Appearance to choose Light, Dark, or System. Your choice is saved in your browser and shared between the admin GUI and sign-in page.
Only global administrator users have access to all configuration settings and the Rspamd webgui. Other users will be presented with settings for only their account, and domains they are managers of. To create a user who is a global administrator for a new installation, the Mailu.env file can be adapted. For more information see the section ‘Admin account - automatic creation’ in the configuration reference.
The following sections are only accessible for global administrators:
send broadcast messages to all users (Menu item Broadcasts)
configure global administration users (Menu item Administrators)
configure relayed domains (Menu item Relayed domains)
access Rspamd webui (Menu item Antispam)
Configure all email domains served by Mailu (Menu item Mail domains)
Settings
After logging in the web administration interface, the settings page is loaded. On the settings page the settings of the currently logged in user can be changed. Changes are saved and effective immediately after clicking the Save Settings button at the bottom of the page. OpenPGP keys have a separate publish button in their settings section.
Display name
On the settings page the displayed name can be changed of the logged in user. This display name is only used within the web administration interface.
OpenPGP keys and Web Key Directory
Users can publish an OpenPGP public key through Web Key Directory (WKD) from
the OpenPGP section of their account settings. WKD lets compatible mail
clients discover a recipient’s public key using their email address. It is
served by the admin application through the existing web server; no additional
container or WKD-specific DNS record is required. The admin interface must be
enabled and its domain must be reachable over HTTPS.
Paste an ASCII-armored public key into the field and click
Publish OpenPGP key. Mailu validates the key with GnuPG, rejects secret key
material, and requires a valid key user ID matching the mailbox. Only the
public key is stored and published. To remove the published key, clear the
field and click Publish OpenPGP key.
Mailu also publishes a user’s key for active, exact aliases currently routed to that mailbox, but only when the key contains a valid user ID matching the alias address. Configured alternative domains are included too, provided the key contains a matching user ID for the address at that alternative domain. Wildcard aliases are not included. If multiple users’ keys contain the same group-alias user ID, WKD returns all of those keys in one response. After changing an alias, its destinations, or a domain alternative, republish the affected users’ keys to refresh the publications.
WKD publication is public. Its hashed lookup names are not a privacy measure: common email local-parts can be guessed. Publish only keys and email addresses you intend to make discoverable.
Antispam
Under the section Antispam the spam filter can be enabled or disabled for the logged in user. By default the spam filter is enabled.
When the spam filter is disabled, all received email messages will go to the inbox folder of the logged in user. The exception to this rule, are email messages with an extremely high spam score. These email messages are always rejected by Rspamd.
When the spam filter is enabled, received email messages will be moved to the logged in user’s inbox folder or junk folder depending on the user defined spam filter tolerance.
When Enable marking spam mails as read is enabled. Received messages moved to the Junk folder are marked as read. When this setting is disabled. Received messages moved to the Junk folder are not marked as read. They remain marked as unread.
The user defined spam filter tolerance determines when an email is classified as ham (moved to the inbox folder) or spam (moved to the junk folder). The default value is 80%. The lower the spam filter tolerance, the more false positives (ham classified as spam). The higher the spam filter tolerance, the more false negatives (spam classified as ham). For more information see the antispam documentation.
Auto-forward
Under the section Auto-forward, the automatic forwarding of received email messages can be enabled. When enabled, all received email messages are forwarded to the specified email address.
The option “Keep a copy of the emails” can be ticked, to keep a copy of the received email message in the inbox folder.
Search for and select one or more destination addresses in the destination field. You can remove a selected address from the field before saving.
Update password
On the update password page, the password of the logged in user can be changed. Changes are effective immediately.
If an administrator requires a password change at next login, the user can change the password or choose Set up a passkey instead. Registering a passkey completes the forced password-change step.
Passkeys
Mailu supports signing in to the Admin and Webmail interfaces with passkeys. Users can register, name, and remove their passkeys from Manage passkeys in their account menu. The page shows each credential’s creation and last-use times, authenticator flags, device type, backup status, attestation format, signature counter, and AAGUID. Some details may show as unknown for older credentials if they were not recorded at enrollment or a later sign-in.
When a user’s account has a passkey, password sign-in and password change are
disabled for that account. The PASSKEY_REQUIRED server setting disables
password sign-in for every account, including accounts without a passkey; users
without one need a manager-generated setup link. Domain-level enforcement
does not disable existing passwords. It requires users without a passkey to
enroll after signing in.
New users are created without an initial password. After creation, give the user the one-time setup link shown on their edit page. They can use it to set a password or add a passkey. Domain managers can generate a replacement setup or recovery link on the same page for users who are locked out or need to reset their password. A link works once and expires after the configured lifetime.
Auto-reply
On the auto-reply page, automatic replies can be configured. This is also known as out of office (ooo) or out of facility (oof) replies.
Enable Automatic reply, compose a formatted message, and choose On selected dates or Until I turn it off. Drag across the calendar to select your time away; on touch screens, press and hold before dragging. You can also enter the first and last day directly. The calendar and date fields stay synchronized. Drag or resize the selected period to change it.
Both selected days are included: replies stop at the end of the last day away, using the mail server timezone shown below the calendar. A one-day vacation uses the same first and last day. Save automatic reply applies the message and schedule; turning the switch off hides the message and schedule controls and retains the saved settings. Use Preview to see the server-sanitized message before saving. Back to editing returns to the composer without changing the draft.
Formatted replies are delivered as HTML with a plain-text alternative. Existing
plain-text API clients remain supported; updating the plain body clears previous
formatting. The optional reply_body_html field is included in configuration
exports. The nullable-column migration retains existing reply text and dates.
Under Reply subject the email subject for automatic replies can be configured. When a reply subject is entered, this subject will be used for the automatic reply.
When no reply subject is entered, the automatic reply will have the subject auto: <subject from received email>. E.g. if the email subject of the received email message is “how are you?”, then the email subject of the automatic reply is auto: how are you?.
Fetched accounts
This page is only available when the Fetchmail container is part of your Mailu deployment. Fetchmail can be enabled when creating the docker-compose.yml file with the setup utility (https://setup.mailu.io).
On the fetched accounts page you can configure email accounts from which email messages will be retrieved. Only unread email messages are retrieved from the specified email account. By default Fetchmail will retrieve email messages every 10 minutes. This can be changed in the Mailu.env file. For more information on changing the polling interval see the configuration reference.
You can add a fetched account by clicking on the Add an account button on the top right of the page. To add an fetched account, the following settings must be configured:
Protocol (IMAP or POP3). The protocol used for accessing the email server.
Hostname or IP. The hostname or IP address of the email server.
TCP port. The TCP port the email server listens on. Common ports are 993 (IMAPS with TLS), 143 (IMAP with STARTTLS), 995 (POP3S with TLS) or 110 (POP3 with STARTTLS).
Enable TLS. Tick this setting if the email server requires TLS/SSL instead of STARTTLS.
Username. The user name for logging in to the email server. Normally this is the email address or the email address’ local-part (the part before @).
Password. The password for logging in to the email server.
Keep emails on the server. When ticked, retains the email message in the email account after retrieving it.
Scan emails. When ticked, all the fetched emails will go through the local filters (rspamd, clamav, …).
Keep original metadata (fetchmail –invisible). When ticked, tries to make Mailu’s fetchmail instance invisible. Normally, fetchmail behaves like any other MTA would – it generates a Received header into each message describing its place in the chain of transmission, and tells the MTA it forwards to that the mail came from the machine fetchmail itself is running on. If the invisible option is on, the Received header is suppressed and fetchmail tries to spoof the MTA it forwards to into thinking it came directly from the mail server host.
Folders. A comma separated list of folders to fetch from the server. This is optional, by default only the INBOX will be pulled.
Click the submit button to apply settings. With the default polling interval, fetchmail will start polling the email account after FETCHMAIL_DELAY.
Make sure FETCHMAIL_ENABLED is set to true in mailu.env to enable fetching and showing fetchmail in the admin interface.
Authentication tokens
On the authentication tokens page, authentication tokens can be created. Authentications tokens are also known as application passwords. The purpose of an authentication token is to create a unique and strong password that can be used by a single application to authenticate as the logged in user’s email account. The application will use this authentication token instead of the logged in user’s password for sending/receiving email. This allows safe access to the logged in user’s email account. At any moment, the authentication token can be deleted so that the application has no access to the logged in user’s email account anymore.
Choose Create and activate token to make a new authentication token. The generated token is displayed only once. After saving the application token it is not possible anymore to view the unique password.
The comment field can be used to enter a description for the authentication token. For example the name of the application the application token is created for.
In the Authorized IP field a comma separated list of white listed IP addresses or networks can be entered. When the field is set, the application token can only be used when the IP address of the client matches what is in the field. When no IP address is entered, there is no restriction on IP address.
Announcement
On the announcement page, the global administrator can send an email message to all email accounts on the Mailu server. This message will be received as an email message in the inbox folder of each user on the Mailu server. The composer shows the configured postmaster sender and the number of recipients. Use the formatting toolbar for headings, emphasis, lists, and links. Messages are sent as HTML with a plain-text alternative; pasted content is sanitized on the server. Images and attachments are not supported.
Choose Send me a test email to deliver a copy only to your administrator mailbox,
with [TEST] in the subject. Your draft remains available for editing.
Choose Preview to review the sanitized message and recipient count, then
Send announcement to confirm the broadcast. Previews expire after 30 minutes
and can only be sent once. Back to editing lets you revise the message.
Delivery results report successful and failed recipients separately. After a partial failure, the retained draft offers a retry only to failed recipients; opening a fresh announcement starts a new broadcast. Delivery is synchronous and drafts are not saved across visits. Leaving a changed composer prompts you before discarding your changes.
Administrators
On the administrators page, global administrators can be added. A global administrator must be an existing user on the Mailu server. A global administrator can change any setting in the admin GUI. Be careful that you trust the user who you make a global administrator.
Relayed domains
On the relayed domains list page, destination domains can be added that Mailu will relay email messages for without authentication. This means that for these destination domains, other email clients or email servers can send email via Mailu unauthenticated via port 25 to this destination domain. For example if the destination domain example.com is added. Any emails to example.com (john@example.com) will be relayed to example.com. Example scenario’s are:
relay domain from a backup server.
allow relay for a specific domain for technical reasons.
relay mails to mailing list servers.
On the new relayed domain page the following options can be entered for a new relayed domain:
Relayed domain name. The domain name that is relayed. Email messages addressed to this domain (To: John@example.com), will be forwarded to this domain. No authentication is required.
Remote host (optional). The host that will be used for relaying the email message. When this field is blank, the Mailu server will directly send the email message to the mail server of the relayed domain. When a remote host is specified it can be prefixed by
mx:orlmtp:and followed by a port number::port).Remote host
Description
postfix transport:nexthop
empty
use MX of relay domain
smtp:domain
:port
use MX of relay domain and use port
smtp:domain:port
target
resolve A/AAAA of target
smtp:[target]
target:port
resolve A/AAAA of target and use port
smtp:[target]:port
mx:target
resolve MX of target
smtp:target
mx:target:port
resolve MX of target and use port
smtp:target:port
lmtp:target
resolve A/AAAA of target
lmtp:target
lmtp:target:port
resolve A/AAAA of target and use port
lmtp:target:port
target can also be an IPv4 or IPv6 address (an IPv6 address must be enclosed in []:
[2001:DB8::], unbracketed IPv6 addresses are rejected).Comment. A text field where a comment can be entered to describe the entry.
Changes are effective immediately after clicking the Save button.
Antispam
The menu item Antispam opens the Rspamd webgui. For more information how spam filtering works in Mailu see the Spam filtering page. The spam filtering page also contains a section that describes how to create a local blacklist for blocking email messages from specific domains. The Rspamd webgui offers basic functions for setting metric actions, scores, viewing statistics and learning.
The following settings are not persistent and are lost when the Antispam container is recreated or restarted:
On the configuration tab, any changes to config files that do not reside in /var/lib or /etc/rspamd/override.d. The last location is mapped to the Mailu overrides folder.
All information on the History tab.
The following settings are persistent and will survive container recreation:
All information on the Status tab
All information on the Throughput tab.
On the Configuration tab, the changes made to action values (greylist, probably spam ….) and config files that reside in /var/lib or /etc/rspamd/override.d. The last location is mapped to the Mailu overrides folder.
Any changes made on the Symbols tab.
Any email messages that have been submitted for spam/ham learning on the Scan/Learn tab.
Mail domains
On the Mail domains page all the domains served by Mailu are configured. Via the new domain button (top right) a new mail domain can be added. Please note that you may have to add the new domain to HOSTNAMES in your mailu.env file. For existing domains you can access settings via the icons in the Actions column and Manage column. From left to right you have the following options within the Action column and Manage column.
Details
This page is also accessible for domain managers. On the details page all DNS settings are displayed for configuring your DNS server. It contains information on what to configure as MX record and SPF record. On this page it is also possible to (re-)generate the keys for DKIM and DMARC. The option for generating keys for DKIM and DMARC is only available for global administrators. After generating the keys for DKIM and DMARC, this page will also show the DNS records for configuring the DKIM/DMARC records on the DNS server. If you have configured alternative domains (see Alternatives below), you will find the MX, SPF, DKIM, and DMARC records of the alternative domains below the entries of the main domain. You can also download a zonefile for easy upload to your nameserver.
Edit
Global administrators can edit all domain settings. Domain managers can open the same page for domains they manage, but can change only settings in the Passkey policy section.
The Require all users to enroll a passkey option requires users without a passkey to set one up after signing in. Existing passwords remain valid for sign-in, but users must complete enrollment before accessing other Mailu pages. When this option is enabled, the per-user Require passkey option is hidden because enrollment is already required for the whole domain.
Domain passkey settings control which credentials may be enrolled and used to sign in. Turn on Enforce AAGUID restrictions to apply the allow or block list; enter AAGUID UUIDs one per line. When enforcement is off, the list is ignored. The policy is checked both at enrollment and at sign-in.
The backup eligibility and backup state settings each support Optional, Require, or Deny. Eligibility describes whether an authenticator can back up a credential; state describes whether that credential is currently backed up. Attestation also supports Optional, Require, or Deny and is evaluated at enrollment. Requiring attestation rejects credentials that provide none, but does not by itself verify that an authenticator is trusted by a manufacturer. User verification (such as a PIN or biometrics), device-bound credentials, resident-key preference, and backup flags are also governed by the domain settings.
By default, signature-counter growth is not enforced. Enable Require signature counter to increase to reject a sign-in unless its counter is greater than the previously stored counter. Some authenticators do not provide a useful increasing counter, so enabling this can prevent those credentials from signing in. User presence is recorded and displayed; WebAuthn requires it for passkey sign-in.
Maximum user count. The maximum amount of users that can be created under this domain. Once this limit is reached it is not possible anymore to add users to the domain; and it is also not possible for users to self-register.
Maximum alias count. The maximum amount of aliases that can be created for an email account.
Maximum user quota. The maximum amount of quota that can be assigned to a user. Enter an integer in MB or GB, up to 1000 of the selected unit (1000 GB is 1 TB). A value of 0 means there is no domain-specific quota limit. When creating or editing a user, this sets the limit on the maximum amount of quota that can be assigned to the user.
Enable sign-up. When this option is ticked, self-registration is enabled. When the Admin GUI is accessed, in the menu list the option Signup becomes available. Obviously this menu item is only visible when signed out. On the Signup page a user can create an email account. If your Admin GUI is available to the public internet, this means your Mailu installation basically becomes a free email provider. Use this option with care!
Comment. Description for the domain. This description is visible on the parent domains list page.
Delete
This page is only accessible for global administrators. This page allows you to delete the domain. The Admin GUI will ask for confirmation if the domain must be really deleted.
Users
This page is also accessible for domain managers. On the users page new users can be added via the Add user button (top right of page). For existing users the following options are available via the columns Actions and User settings (from left to right)
Edit. Configure the user’s account details and next-login requirements. For all available options see the Add user page.
Delete. Disables the user. For more information on permanently deleting users, refer to the How to delete users page.
Settings. Access the settings page of the user. See the settings page for more information.
Auto-reply. Access the auto-reply page of the user. See the auto-reply page for more information.
Fetched accounts. Access the fetched accounts page of the user. See the fetched accounts page for more information.
Passkeys. Open the user’s passkey page to review or remove registered keys. Use Edit to generate a one-time setup or recovery link for a user who is locked out or needs to set a password or passkey. The link can be generated by global administrators or managers of the user’s domain. It works without an existing sign-in and expires after the configured lifetime; generating a replacement invalidates the previous link for that user.
This page also shows an overview of the following settings of an user:
Email. The email address of the user.
Features. Shows if IMAP or POP3 access is enabled and whether the user should be allowed to spoof emails.
Storage quota. Shows how much assigned storage has been consumed.
Sending Quota. The sending quota is the limit of messages a single user can send per day.
Comment. A description for the user.
Created. Date when the user was created.
Last edit. Last date when the user was modified.
Add user
For adding a new user the following options can be configured.
E-mail. The email address of the new user.
Require passkey. Require the user to set up a passkey before they can sign in. After creating the account, copy the one-time setup link from the user’s edit page and give it to them. The user can use the link to set a password or set up a passkey, subject to the server and domain passkey policies.
On an existing user’s edit page, Force password change at next login remains available. Use Generate one-time setup or recovery link when the user is locked out or needs to choose a new password or passkey. Each generated link invalidates the previous link for that account.
Displayed name. The display name of the user within the Admin GUI.
Comment. A description for the user. This description is shown on the Users page.
Enabled. Tick this checkbox to enable the user account. When an user is disabled, the user is unable to login to the Admin GUI or webmail or access his email via IMAP/POP3 or send mail. The email inbox of the user is still retained. This option can be used to temporarily suspend an user account.
Storage Quota. The maximum quota for the user’s email box. Enter an integer in MB or GB, up to 1000 of the selected unit (1000 GB is 1 TB), subject to the domain’s maximum user quota. A value of 0 means unlimited.
Allow IMAP access. When ticked, allows email retrieval via the IMAP protocol.
Allow POP3 access. When ticked, allows email retrieval via the POP3 protocol.
Allow the user to spoof the sender. When ticked, allows the user to send email as anyone.
Aliases
This page is also accessible for domain managers. On the aliases page, aliases can be added for email addresses. An alias is a way to disguise another email address. Everything sent to an alias email address is actually received in the primary email account’s inbox of the destination email address. Aliases can diversify a single email account without having to create multiple email addresses (users). It is also possible to add multiple email addresses to the destination field. All incoming mails will be sent to each users inbox in this case.
The following options are available when adding an alias:
Alias. The alias to create for the specified email address. You cannot use an existing email address.
Use SQL LIKE Syntax (e.g. for catch-all aliases). When this option is ticked, you can use SQL LIKE syntax as alias. The SQL LIKE syntax is used to match text values against a pattern using wildcards. There are two wildcards that can be used with SQL LIKE syntax:
% - The percent sign represents zero, one, or multiple characters
_ - The underscore represents a single character
- Examples are:
a% - Finds any values that start with “a”
%a - Finds any values that end with “a”
%or% - Finds any values that have “or” in any position
_r% - Finds any values that have “r” in the second position
a_% - Finds any values that start with “a” and are at least 2 characters in length
a__% - Finds any values that start with “a” and are at least 3 characters in length
a%o - Finds any values that start with “a” and ends with “o”
Destination. The destination email address for the alias. Click in the Destination text box to access a drop down list where you can select a destination email address.
Comment. A description for the alias. This description is visible on the Alias list page.
Managers
This page is also accessible for domain managers. On the managers list page, managers can be added for the domain and can be deleted. Managers have access to configuration settings of the domain. On the add manager page you can click on the manager email text box to access a drop down list of users that can be made a manager of the domain.
Alternatives
This page is only accessible for global administrators. On the alternatives page, alternative domains can be added for the domain. An alternative domain acts as a copy of a given domain. Everything sent to an alternative domain, is actually received in the domain the alternative is created for. This allows you to receive emails for multiple domains while using a single domain. For example if the main domain has the email address user@example.com, and the alternative domain is mymail.com, then email send to user@mymail.com will end up in the email box of user@example.com.
New domain
This page is only accessible for global administrators. Via this page a new domain can be added to Mailu. The following options must be defined for adding a domain:
domain name. The name of the domain.
Maximum user count. The maximum amount of users that can be created under this domain. Once this limit is reached it is not possible anymore to add users to the domain; and it is also not possible for users to self-register.
Maximum alias count. The maximum amount of aliases that can be made for an email account.
Maximum user quota. The maximum amount of quota that can be assigned to a user. Enter an integer in MB or GB, up to 1000 of the selected unit (1000 GB is 1 TB). A value of 0 means there is no domain-specific quota limit. When creating or editing a user, this sets the limit on the maximum amount of quota that can be assigned to the user.
Enable sign-up. When this option is ticked, self-registration is enabled. When the Admin GUI is accessed, in the menu list the option Signup becomes available. Obviously this menu item is only visible when signed out. On the Signup page a user can create an email account. If your Admin GUI is available to the public internet, this means your Mailu installation basically becomes a free email provider. Use this option with care!
Comment. Description for the domain. This description is visible on the parent domains list page.
Webmail
The menu item Webmail opens the webmail page. This option is only available if the webmail container is running and is enabled in the mailu.env file.
Client setup
The menu item Client setup shows the settings for connecting an email client to Mailu and encourages use of authentication tokens. Create a separate token for each app or device, then save it in the client’s incoming and outgoing password fields. The token is intended to be set once and left in the mail client; it is not your password for signing in to the web interface. Email-client password authentication can be restored by an administrator setting AUTH_REQUIRE_TOKENS=False.
Website
The menu item Website forwards the user to the URL that is configured in variable WEBSITE=xxxxx in the mailu.env environment file.
Help
The menu item Help links to the official Mailu documentation website https://mailu.io/
Sign out
The menu item Sign out signs out the currently logged in user.
Account selection in access forms
When adding managers, global administrators, or Anonymous Email Access, search by email address or display name and select multiple accounts before submitting. Selected accounts appear as removable chips. Accounts already granted the role are marked in the results. Search returns at most 50 matches; continue typing to narrow large lists. The server checks every selected account before applying the batch, using the same permission scope as the corresponding form.