Mail Configuration Reference
Sympl uses a combination of Exim and Dovecot, along with some custom authentication systems to provide the full suite of email functionality, including support for anti-virus, anti-spam and email deliverability systems such as SPF, DKIM and DMARC.
This page has a breakdown of the configuration options and files used when handling email for a domain.
To accept email for a domain, one of the below methods must be enabled. Any email sent to an address not covered by one of these will be rejected.
/srv/example.com/mailboxes/ directory contains the user mailboxes, so the existence of the directory
/srv/example.com/mailboxes/alice would accept mail for the email address
/srv/example.com/mailboxes/bob would accept mail for
firstname.lastname@example.org and so on. Once these directories have been created, the mailbox will receive mail, and can be accessed via IMAP, POP3 or Webmail once a password has been set.
In some cases you may want to have multiple (internal or external) email addresses attached to the same mailbox. This is done using
/srv/example.com/config/aliases, which is a file containing the local part followed by a comma separated list of email addresses. For example:
webmaster email@example.com info firstname.lastname@example.org, email@example.com alice.smith firstname.lastname@example.org bob.jones email@example.com charlie.williams firstname.lastname@example.org staff email@example.com, firstname.lastname@example.org, email@example.com dave.taylor firstname.lastname@example.org dave email@example.com
Note that when using external email addresses which are not hosted on the same server, then the mail is forwarded on directly without the sender being rewritten, which may cause delivery issues if the sender or recipient are using any anti-spam measures.
For this reason, it is generally best to either deliver to a local mailbox which is collected by the user, or to use a Sieve forward rule in a local mailbox to ensure delivery.
Mail for Local System Users
Sympl also manages email for local system users, however this only applies to mail either addressed to the local domain, or internal mail sent without a destination domain. These are managed slightly differently, and are overridden at a mailbox level by the existence of an individual mailbox.
Accepting All Mail
/srv/example.com/config/default_forward file acts as a fallback or catchall for any mail not covered by an existing mailbox or alias. This will then accept all mail, regardless of addressing.
See the Forwarding Mail section below for more information.
Suffixes and Plus Addressing
Sympl supports 'plus addressing suffixes for mailboxes. These are added to the local part of the email address after a plus (+) character, and can be used for filtering incoming email on the
To: field or other purposes.
As an example, to filter all mail from a specific supplier regardless of their sender address, Alice may provide them
firstname.lastname@example.org as her email address, which will be delivered to the
email@example.com mailbox as normal.
The password for a user mailbox is set by the contents of the individual
/srv/example.com/mailboxes/user/password file. The contents of this file can be either encrypted or plain text, which will be automatically encrypted as part of the daily cron jobs.
All passwords should be as long and complex as practical. A password of at least 16 characters with mixed case alphanumeric is suggested as minimum.
To force immediate encryption of any plain text email passwords, run
sudo sympl-mail-encrypt-passwords --verbose.
User Password Change
Users are able to change their own passwords via the Webmail interface.
- Log into webmail with the current password
- Click 'Settings' in the top right.
- Click 'Password' in the list on the left.
- Change the password using the web form.
Note that the system will perform password strength checks, so attempting to set a weak or short password will fail with a relevant error message.
Resetting a User Password
If the password is not known and needs to be reset, then the
/srv/example.com/mailboxes/user/password file can simply be updated with the new password.
Server-Side Rules with Sieve Filtering
These rules can be used to mark messages read, flag mail, move mail into separate folders, as well as forward and reply to mail, without a mail client needing to be connected.
Each mailbox can create a number of rule sets in the
/srv/example.com/mailboxes/user/sieve.d directory, with the
/srv/example.com/mailboxes/user/sieve file being the active file.
Note that only one file may be active at a time for each mailbox, so the user should add to existing rules rather than creating a new set.
Using roundcube webmail users can access a mailbox's Sieve rules by logging in and going to 'Settings' > 'Filters'.
Mail can be forwarded via two methods, either at a mailbox level, or at the domain level as a catch-all for any addresses which do not otherwise exist.
Note that like aliases, when using external email addresses which are not hosted on the same server, then the mail is forwarded on directly without the sender being rewritten, which may cause delivery issues if the sender or recipient are using any anti-spam measures. With this in mind, it's suggested to use Sieve filters where possible when communicating with external domains.
For individual mailbox forwarding, the file is located at
/srv/example.com/mailboxes/user/forward, and to forward all mail which is not already handled via another method, the file is
/srv/example.com/config/default_forward. Format of these files is identical, and can be one of two formats.
Comma Separated List
The most basic format is a comma-separated list of email addresses to forward the mail to, for example, to deliver all mail sent to
/srv/example.com/mailboxes/bob/forward you would place the text:
Note that this method will redirect all incoming mail, preventing it from being delivered to the
Exim Filter File
A more complex format is using Exim filter file, which are fully documented in the Exim project documentation. Some common examples are below.
Forward a copy of the mail and deliver normally
This delivers the mail to the mailbox as normal, but also sends a copy to both firstname.lastname@example.org and email@example.com, but also delivers it to firstname.lastname@example.org, and would be located in
# Exim filter unseen deliver email@example.com unseen deliver firstname.lastname@example.org
Redirect all mail to another domain
This redirects all mail to the domain
example.org, retaining the local part. This is much more useful at
/srv/example.com/config/default-forward rather than in a mailbox, and acts similar to a web redirect.
# Exim filter deliver $email@example.com
A vacation message can be set to auto-reply to incoming messages on a users mailbox by creating
/srv/example.com/mailboxes/user/vacation, and adding the text to be sent as an auto-reply.
Please note that vacation messages can annoy other email users as they will automatically reply to all messages from users they have no recently sent a message to. This can cause annoyance with mailing lists, email bounces and so on, and while an effort is made to negate this as much as possible, it is not entirely safe.
Actions for the vacation rules are logged in
/srv/example.com/mailboxes/user/vacation.log, with a machine-readable database of the replies in
/srv/example.com/mailboxes/user/vacation.db, and once the vacation rules are no longer needed, all three files
vacation.db should all be removed.
Sympl can enforce mailbox size quotas on user accounts, preventing too much space being used on the server.
To set a quota for all mailboxes, create the file
/srv/example.com/mailbox-quota, or for a single mailbox, create
/srv/example.com/mailboxes/user/quota. Any quota set on a mailbox individually will override a quota at the domain level.
The contents of this file are the maximum size of the mailbox in bytes if no suffix is used, otherwise the normal file size suffixes are used.
For example, the text
/srv/example.com/mailbox-quota limits all mailboxes to a maximum of 1 Gibibyte, and the text
/srv/example.com/mailboxes/bob/quota would allow
firstname.lastname@example.org to store twice as much mail.
Alternatively, the value
0 (zero) is the default and disables any quota, allowing you to set an overall quota, but disable it for specific users.
Rate Limiting Outbound Mail
Sympl can easily be configured to limit the number of outbound mails, either on a per-mailbox or per-domain basis, and you may want to implement this limit to prevent mail abuse.
To set it for a mailbox, add the file
/srv/example.com/mailboxes/user/ratelimit or for a domain use the file
/srv/example.com/config/mailbox-ratelimit. If both files exist, the mailbox-specific file takes precedence.
In both cases, the value in the file should be the maximum number of mails which can be sent in one hour. If the file exists but is blank or contains a non-numeric value, a default of 100 mails/hour is applied.
Any emails beyond this number will be rejected and the sender will receive a failed delivery notification.
The protection is based on the smtp authenticated user and works across all authenticated sessions so might include multiple mail clients / devices.
Enabling DomainKeys Identified Mail (DKIM)
DomainKeys Identified Mail, better known as DKIM, is a a standard which validates that the email did come from an authorised server. It involves the server cryptographically signing outgoing email using a private key, which can then be used to validate the email via a public key which is available via a DNS request.
To enable DKIM, you first need to generate the key and set the relevant permissions, with
openssl genrsa -out /srv/example.com/config/dkim.key; chmod 660 /srv/example.com/config/dkim.key - this is the private key which will be used to sign outgoing email.
Next create the file
/srv/example.com/config/dkim, which enables DKIM, and sets the 'selector', which is a unique identifier for the server/key. This defaults to the short hostname of your server (or
default if this can't be determined), but can be changed to a relevant string.
Next you should run
sudo sympl-dns-generate, and add the DKIM record from
/srv/example.com/config/dns/example.com.txt to the DNS for your domain.
For more email deliverability features including Sender Policy Framework (SPF) and Domain-based Message Authentication, Reporting & Conformance (DMARC), see DNS Configuration Reference
There is a useful tool at https://www.appmaildev.com/en/dkim for testing whether DKIM is working.
Anti-Spam and Anti-Virus Scanning
Note that while the systems mentioned below are able to deal with a significant proportion of spam they will not be able to filter 100% of spam as there is a continuous arms race in progress, however reputable senders will likely be using SPF, DKIM, and DMARC to improve mail delivery.
Also please note that both of these methods, (especially
antivirus) have significant memory footprints, and enabling anti-virus on systems with less than 2GB of RAM can leads to out-of-memory issues and system instability.
- To enable anti-virus, and reject mail identified as containing a virus, create the empty file
- To enable anti-spam and reject mail identified as spam, create the empty file
Alternatively, to enable anti-spam and 'tag' mail identified as spam, create file
/srv/example.com/config/antispam containing the text
tag. This will cause the email to be delivered as normal with headers added, and prepend the text '
[spam]' to the subject.
Filtering Mail Using Headers
When emails are passed through the anti-spam and anti-virus filters, specific headers are added to the mail with diagnostic information. These can be used by mail clients or Sieve filters to move the mail into relevant folders of the mailbox.
With anti-spam enabled, any mail accepted will have the headers
X-Spam-Status added by SpamAssassin.
X-Spam-Scoreheader contains the score and and rules which were matched when the mail was received, and the higher the score the more certain SpamAssassin is that the mail is unwanted.
X-Spam-Barheader contains a graphical representation of the score using plusses (for positive values) and minuses (for negative values).
X-Spam-Statusheader contains either
spamdepending on the result.
With anti-virus enabled, the header
X-Anti-Virus is added to mail which has been scanned. This header is either the text
Adjusting SpamAssassin Sensitivity
The configuration for SpamAssassin will be automatically created after it has been enabled and has received the first email, and is located in
/home/sympl/.spamassassin/user_prefs. In the file, you can adjust the score threshold needed mark an email as spam by adjusting the
required_score to a lower figure than the default value of
5 and un-commenting the line by removing the preceding
#. If you find mail is being rejected when it shouldn't be, you can increase the value.
Further information on configuring SpamAssassin can be found at the SpamAssassin Wiki. Note that there is not currently any functionality within Sympl to help train the SpamAssassin Bayesian learner, or adjust the scoring for individual domains or mailboxes.
Real-Time Block Lists
- The Spamhaus Block List (SBL), a database of IP addresses from which Spamhaus does not recommend the acceptance of electronic mail.
- The Exploits Block List (XBL), a realtime database of IP addresses of hijacked PCs infected by illegal 3rd party exploits, including open proxies, worms/viruses with built-in spam engines, and other types of trojan-horse exploits.
- The Policy Block List (PBL), a database of end-user IP address ranges which should not be delivering unauthenticated SMTP email to any Internet mail server except those provided for specifically by an ISP for that customer's use.
These three lists are then combined to for the 'Zen' list.
To enable the lists, create an empty file at one or more of these locations:
/srv/example.com/config/blacklists/sbl.spamhaus.orgto enable the SBL list.
/srv/example.com/config/blacklists/xbl.spamhaus.orgto enable the XBL list.
/srv/example.com/config/blacklists/pbl.spamhaus.orgto enable the PBL list.
/srv/example.com/config/blacklists/sbl-xbl.spamhaus.orgto enable the combined SBL and XBL list.
/srv/example.com/config/blacklists/zen.spamhaus.orgto enable the combined SBL, XBL, and PBL list.
Sympl allows you to blacklists specific senders for all local domains with changes to the server-wide Exim configuration. Note that the following changes should be made as the
root user rather than the normal
sympl user, as this covers all incoming email.
Blacklist by Email Address
To block a specific sender, add the email address to
/etc/exim4/blacklist/by_sender. This also accepts wildcard addresses such as
user@*. Note that this matches against the envelope sender rather than the from address.
Blacklist by Hostname
To block mail from a specific hostname, add the name to
/etc/exim4/blacklist/by_hostname. This accepts both full domain names such as
mail.example.com and wildcards such as
*.example.com, and matches against the reverse DNS of the connecting server.
Blacklist by IP Address
Blocking mail from a specific IP address can be done by adding the IP or range to
/etc/exim4/blacklist/by_ip. This accepts both single addresses such as
172.16.17.18 as well as CIDR ranges such as
172.16.17.0/24, and matches against the IP address of the connecting server.
Setting A Specific IP For Sending Email
sympl-mail package uses the same
/srv/example.com/config/ip file as the
sympl-web package to determine which IP address mail should be sent from. Note that when using an IPv6 address, the IP address should have a reverse DNS entry to ensure email deliverability.
Local System User Mail
Note: It both a normal mailbox exists as well as a local system user on the same domain, then the mailbox will take precedence.
Other than accepting mail for users in a
/srv/example.com/mailboxes/ directory, Sympl also manages mailboxes for local system users based on their home directories and local users will receive email to
<username>@<hostname of the server>. Mail for these users is stored in the users home directory in a
Maildir/ directory, and users may use local mail reader apps to access it, negating the need for SMTP/IMAP, or may use Webmail with the plain username without the domain (the
There are a number of differences in configuration names due to the users home directory being used, these are:
Mail is configured to use the default ports, with STARTTLS enabled on legacy ports.
|TLS Enabled by
|File or Directory
|Contains a list of IP addresses which mail will be sent from for the domain. Defaults to the primary IPs (IPv4 and IPv6) of your server.
|Contains a list of email aliases for this domain.
|Configures what to do with mail sent to accounts which do not exist.
|Sets a maximum size in bytes for each mailbox. Defaults to
0, no quota.
|Sets a maximum number of emails which can be sent in 24 hours. Defaults to
|Enables DKIM and sets the selector. Defaults to short hostname or default if that can't be determined.
|Contains the DKIM private key used to sign outgoing email.
|Enables anti-spam filtering for the domain and rejects suspect mail. Setting the content to
tag allows email in but tags the subject with the text ''[spam]".
|Enables anti-virus filtering for the domain, rejecting flagged emails.
|Enables the SpamHaus Block List
|Enabled the SpamHaus Exploits Block List
|Enables the SpamHaus Policy Block List
|Enables both the SpamHaus Block List and the Exploits Block List
|Enables the SpamHaus Block List, the Exploits Block List, and SpamHaus Policy Block List
See also Configuration Reference for other configuration files.
|File or Directory
|Mail and configuration for the
|The users mailbox and folder structure. Created automatically when the first mail is received.
|Encrypted or plain text copy of the password for the mailbox.
|Sets a maximum size in bytes for this mailbox. Defaults to
0, no quota. Overrides
|Sets a maximum number of emails which can be sent in 24 hours. Defaults to
|Comma Separated email addresses or Exim Filter format rules for mail delivery to this mailbox.
|Vacation message which will be returned to each sender.
|Log of email received while the
vacation file was in place, and the action taken.
|Machine readable database of emails which have been sent to avoid duplicate replies.
|Currently active Sieve rules on the mailbox.
|Directory containing other available Sieve rulesets.