Mail Configuration Reference

From Sympl Wiki
Jump to navigation Jump to search

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.

Accepting Email

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.

Individual Mailboxes

The /srv/ directory contains the user mailboxes, so the existence of the directory /srv/ would accept mail for the email address, /srv/ would accept mail for 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.

Mailbox Aliases

In some cases you may want to have multiple (internal or external) email addresses attached to the same mailbox. This is done using /srv/, which is a file containing the local part followed by a comma separated list of email addresses. For example:

info    ,
alice.smith       alice@example.dom
staff   ,,

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

The /srv/ 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 as her email address, which will be delivered to the mailbox as normal.

Mailbox Passwords

The password for a user mailbox is set by the contents of the individual /srv/ 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.

  1. Log into webmail with the current password
  2. Click 'Settings' in the top right.
  3. Click 'Password' in the list on the left.
  4. 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/ file can simply be updated with the new password.

Server-Side Rules with Sieve Filtering

Sieve is a standardised language for filtering incoming mail on the server directly on the server without having shell access, either using a Sieve client or through the webmail interface.

These rules can be used to mark messages read, flag mail, move mail into seperate 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/ directory, with the /srv/ 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.

Users can access a mailboxes Sieve rules by logging in and going to Settings (top right), then selecting 'Filters' from the list on the left.

Forwarding Mail

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/, and to forward all mail which is not already handled via another method, the file is /srv/ 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 to and, in /srv/ you would place the text:,

Note that this method will redirect all incoming mail, preventing it from being delivered to the mailbox.

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 and, but also delivers it to, and would be located in/srv/

# Exim filter
unseen deliver
unseen deliver

Redirect all mail to another domain

This redirects all mail to the domain, retaining the local part. This is much more useful at /srv/ rather than in a mailbox, and acts similar to a web redirect.

# Exim filter
deliver $

Vacation Messages

A vacation message can be set to auto-reply to incoming messages on a users mailbox by creating /srv/, 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/, with a machine-readable database of the replies in /srv/, and once the vacation rules are no longer needed, all three files vacation, vacation.log and vacation.db should all be removed.

Size Quotas

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/, or for a single mailbox, create /srv/ 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 1Gi in /srv/ limits all mailboxes to a maximum of 1 Gibibyte, and the text 2Gi in /srv/ would allow 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/ or for a domain use the file /srv/

In both cases, the value in the file should be the maximum number of mails which can be sent in a 24 hour period, if the file exists but is blank, the default of 100 mails/day is applied.

Any emails beyond this number will be sent an error and the email will be discarded.

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/; chmod 660 /srv/ - this is the private key which will be used to sign outgoing email.

Next create the file /srv/, 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/ 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 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.

Sympl primarily uses SpamAssassin (anti-spam) and ClamAV (anti-virus) to protected mailboxes from spam.

  • To enable anti-virus, and reject mail identified as containing a virus, create the empty file /srv/
  • To enable anti-spam and reject mail identified as spam, create the empty file /srv/

Alternatively, to enable anti-spam and 'tag' mail identified as spam, create file /srv/ 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-Score, X-Spam-Bar and X-Spam-Status added by SpamAssassin.

  • The X-Spam-Score header 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.
  • The X-Spam-Bar header contains a graphical representation of the score using plusses (for positive values) and minuses (for negative values).
  • The X-Spam-Status header contains either innocent or spam depending on the result.

With anti-virus enabled, the header X-Anti-Virus is added to mail which as been scanned. This header is either the text infected or clean.

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

There are three Real Time Block Lists from Spamhaus which can be used to check the sending mail server's IP against for various types of bad behavior.

  • 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/ to enable the SBL list.
  • /srv/ to enable the XBL list.
  • /srv/ to enable the PBL list.
  • /srv/ to enable the combined SBL and XBL list.
  • /srv/ to enable the combined SBL, XBL, and PBL list.

Blacklisting Senders

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 * and 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 and wildcards such as *, 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 as well as CIDR ranges such as, and matches against the IP address of the connecting server.

Setting A Specific IP For Sending Email

The sympl-mail package uses the same /srv/ 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/ 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 part).

There are a number of differences in configuration names due to the users home directory being used, these are:

mailboxes/user/password /home/user
Maildir/ Maildir/
password .password
forward .forward
vacation .vacation
sieve .sieve

Port Configuration

Mail is configured to use the default ports, with STARTTLS enabled on legacy ports.

Service Port Encryption TLS Enabled by
SMTP 465 TLS On connection
POP3 995 TLS On connection
IMAP 993 TLS On connection
Sieve 4190 TLS On connection

Configuration Reference

File or Directory Used For More
.../config/ip 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. More...
.../config/aliases Contains a list of email aliases for this domain. More...
.../config/default_forward Configures what to do with mail sent to accounts which do not exist. More...
.../config/mailbox_quota Sets a maximum size in bytes for each mailbox. Defaults to 0, no quota. More...
.../config/mailbox_ratelimit Sets a maximum number of emails which can be sent in 24 hours. Defaults to 100. More...
.../config/dkim Enables DKIM and sets the selector. Defaults to short hostname or default if that can't be determined. More...
.../config/dkim.key Contains the DKIM private key used to sign outgoing email. More...
.../config/antispam Enables anti-spam filtering for the domain. Setting the content to tag allows email in but filters it to the Spam folder in the mailbox. More...
.../config/antivirus Enables anti-virus filtering for the domain. More...
.../config/blacklists/ Enables the SpamHaus Block List More...
.../config/blacklists/ Enabled the SpamHaus Exploits Block List More...
.../config/blacklists/ Enables the SpamHaus Policy Block List More...
.../config/blacklists/ Enables both the SpamHaus Block List and the Exploits Block List More...
.../config/blacklists/ Enables the SpamHaus Block List, the Exploits Block List, and SpamHaus Policy Block List More...

See also Configuration Reference for other configuration files.

Mailbox Reference

File or Directory Used For More
/srv/ Mail and configuration for the More...
/srv/ The users mailbox and folder structure. Created automatically when the first mail is received. More...
/srv/ Encrypted or plain text copy of the password for the mailbox. More...
/srv/ Sets a maximum size in bytes for this mailbox. Defaults to 0, no quota. Overrides config/mailbox_quota. More...
/srv/ Sets a maximum number of emails which can be sent in 24 hours. Defaults to 100. More...
/srv/ Comma Separated email addresses or Exim Filter format rules for mail delivery to this mailbox. More...
/srv/ Vacation message which will be returned to each sender. More...
/srv/ Log of email received while the vacation file was in place, and the action taken. More...
/srv/ Machine readable database of emails which have been sent to avoid duplicate replies. More...
/srv/ Currently active Sieve rules on the mailbox. More...
/srv/ Directory containing other available Sieve rulesets. More...