Chapter 5. Email Configuration

Table of Contents

5.1. Port Configuration
5.2. Accepting email for a domain
5.3. Email for Unix users.
5.4. Password files
5.5. Allowing users to change their own password
5.6. Suffixes
5.7. Enforcing mailbox size with quotas
5.8. Server-side filtering using Sieve
5.9. Forward files
5.10. Vacation messages
5.11. Email alias lists
5.12. Spam and virus scanning
5.13. Customising SpamAssassin
5.14. Filtering mail using headers
5.15. Using real-time blacklists from Spamhaus
5.16. Manually blocking incoming mail from specific sources
5.17. Rate limiting outbound email
5.18. Setting an outbound IP for all email from a domain
5.19. Blocking email
5.20. Enabling SNI for Exim and Dovecot
5.21. Configuration layout

This is a detailed break-down of all the configuration options and files available when configuring how email is handled for a domain. Throughout this chapter, the domain is used as an example. Thus all the configuration for will be inside the /srv/ directory.

5.1. Port Configuration

The mail servers have been set up with standard port assignments as follows. These are all the standard ports for the protocols.

Service Port Encryption








25 or 587




TLS (on connect)



TLS (on connect)



TLS (on connect)




5.2. Accepting email for a domain

In order for a domain to be configured to accept email, one of two things must be present. Either the domain must have a mailboxes/ directory present, or one of the files config/default_forward or config/aliases must be present.

For example, if the domain would like to host mail normally, i.e. one mailbox per user hosted on the same machine, then the directory /srv/ should be created. Then in there, one directory per user should be created. If would like to receive mail, then /srv/ should be created.

Once this directory has been created, this mailbox can be accessed via IMAP/POP3, or Roundcube webmail. For example, the mailboxes for would be accessible at

Assuming that this is the only directory inside /srv/ then only mail addressed to will be accepted. Any other mail addressed to will be rejected.

If you would like to accept all mail for, regardless of who it is addressed to, then create the file /srv/ The contents of this file should be a single email address, or a comma-separated list of email addresses. For example, to forward all mail to, unless the recipient’s mailbox already exists, then /srv/ should contain

If you would like the domain not to receive any mail at all, then remove the directory /srv/ and ensure that the file /srv/ does not exist.

5.3. Email for Unix users.

Before you start this section

  1. Both a unix user and a normal Symbiosis email user can be set up to receive email to the same address. The normal user will always take precedence over the unix user and have their mail delivered to their inbox first, so take care when using this feature!

A new feature in this release is the ability to have unix users with email accounts based in their home directories. These will receive emails for the host name of the machine, which you can find out by running hostname on the command line. The result of this will display the domain in the email address the system users will get, eg, the part after the @. The other half will be dictated by their username, eg, "admin" or "my-user".

To start with, we create a .password file in, eg, /home/my-user/. Initially this can contain the password in plain text.

Once the password file is in place, the new user will be able to login and collect email. Logins over SMTP, IMAP, and POP3 will all work identically to a normal email user, with the same ports and SSL/TLS requirements. The principal difference is the username is just their bare username, without a domain. E.g. for a user clare, her login for SMTP/IMAP/POP3 etc, is just clare.

Unix users' Maildir directories will reside in /home/my-user/Maildir by default. This allows these users to use system mail readers such as mutt in order to read and send email, obviating the need to use IMAP and SMTP.

These users are also able to control the following files:

  • .forward - to control forwarding of emails.
  • .vacation - to set a vacation (holiday) message.
  • .sieve - to set up Sieve filters.

5.4. Password files

The password for a mailbox should be set by the contents of a file named password inside a user’s mailbox directory. The contents of this file may be in plain text, or encrypted. If plain text is used, the system will automatically encrypt the password.

To encrypt all email passwords on the system, you can run

`symbiosis-email-encrypt-passwords --verbose`

The --verbose flag is there to provide more output.

5.5. Allowing users to change their own password

Users are able to change their own passwords through the webmail system, which by default is Roundcube.

To change a password in Roundcube, log in and select Options. This will being up the Options page :

From there, select Change Password, where you must enter your current password, and enter a new one. Passwords which are ether too weak or too short will be rejected by the system.

5.6. Suffixes

All email addresses can be used with a suffix. This allows people to filter their email by the To: address. The separator between the local part and suffix is the + sign.

For example, Bob signs up to a shopping site at He might use his email address when signing up, such that he can filter all email from that shop.

5.7. Enforcing mailbox size with quotas

Symbiosis can enforce users' mailbox size with quotas. This will prevent mail from being delivered to a user if their mailbox grows too large.

A default quota for each individual mailboxes in a domain can be specified in config/mailbox-quota. A per-mailbox quota can be defined in a file named quota which resides in a user’s mailbox directory.

These files both have the same format, which is just a number of bytes over which mail should not be delivered. This number can have a suffix of k, M, or, G which represent kilobytes, megabytes, and gigabytes, or ki, Mi, or Gi to represent kibibytes, mebibytes, and gibibytes, respectively.

For example, to limit the size of each mailbox for the domain to 200MB, i.e. 200,000,000 bytes, put 200M in /srv/

To grant a 1GiB quota, i.e. 1,073,741,824 bytes, put 1Gi in /srv/

Quotas in a user’s mailbox directory take precedence over the default quota.

5.8. Server-side filtering using Sieve

Sieve is a standard language that users can employ to filter their email on the server. Additionally using any one of a number of clients, users can edit their filtering rules without needing shell access to the server.

Each user can create a number of scripts in a directory called sieve.d/, with the current script being kept in a file called sieve.

Only one of these scripts can be active at a given time for each user; add to an existing file rather than creating a new one if you require extra filters.

5.9. Forward files

There are two methods of forwarding email. The first is a per-mailbox forwarding service, and the second is a per-domain service. For the per-user service, a file named forward should be put in a user’s mailbox directory. The per-domain service uses the same file format as the per-user service, but the file should be uploaded to config/default_forward instead.

For example, would set up a file called /srv/

If all the mail for needed to be forwarded elsewhere, then the file would be called /srv/

Both of these files can be interpreted in two ways. Firstly they can be a comma separated list of email addresses. For example, if Bob wanted to forward his email onto Charlie and Dave, his forward file might read,

The second way these files are interpreted is as an Exim filter file. The full specification is documented at the Exim project site.

Here are some examples of what is possible.

To forward mail on, but keep a copy

# Exim filter
unseen deliver
unseen deliver

To rewrite all mail for a domain to This is probably best used in config/default_forward.

# Exim filter
deliver $

The Exim documentation has further examples of what is possible.

5.10. Vacation messages

It is possible to set a vacation message for a user by putting a message in file called vacation in the user’s mailbox directory.

For example, for, the message would go in /srv/ On Bob’s return, the people who received vacation messages are logged to /srv/ Once he’s read it, that file, along with /srv/ and /srv/ should all be removed.


Vacation messages can irritate other email users by replying to mailing lists, email bounces, and so on. Every effort is made to stop this from happening, but it is by no means fool-proof.

5.11. Email alias lists

Each domain can have a list of aliases. This is just a file that contains a list of local parts, and a list of places they should be sent on to. This file should be in the config/ directory and is named aliases.

For example, has a list of dummy addresses that should be sent on to Bob. So the aliases file would be kept at /srv/ and contains the following.


This ensures that is sent to; is sent to; is sent to,, and

5.12. Spam and virus scanning

Symbiosis comes with SpamAssassin and ClamAV installed to protect your email users against spam and virus in their inbox. To enable these features, simply create the files config/antispam or config/antivirus as appropriate. This will configure that domain to reject email if it is considered to be spam, or if it contains a virus.

If you’d rather accept all email and simply tag it as spam, put the word tag in config/antispam. This will also cause the email to be delivered into the Spam/ folder for that user.

5.13. Customising SpamAssassin

The configuration for SpamAssassin for the admin user is kept in /srv/.spamassassin/user_prefs. Here you can adjust what score is needed to reject spam, and which tests are used during scanning. This file will only appear after a mail has been received with spam detection turned on, but one can be created and configured before this occurs.

The file contains comments and instructions, and further tips can be found on the SpamAssassin wiki.

In brief, to cause more mail to be rejected, you need to reduce the threshold score. Therefore change the line reading # required_score 5 should be changed to required_score 4. Notice that the # has been removed at the start of the line to un-comment it.

Similarly if mail is being rejected, you can increase the score.

Further instructions can be found on the SpamAssassin wiki.

There is no facility to train the SpamAssassin Bayesian learner yet.

5.14. Filtering mail using headers

Headers are added to messages when spam or virus scanning is enabled. These can be used by email clients to filter email, for example in to spam or quarantine folders.

With spam scanning enabled, any email that is accepted has the following headers added

  • X-Spam-Score
  • X-Spam-Bar
  • X-Spam-Status

The score is determined by SpamAssassin, and is the basis for acceptance or rejection. The higher the score, the more certain SpamAssassin is that the message is unwanted. The default threshold for rejection is 5.

The bar is a length of pluses or minuses that provide an easy-to-parse representation of the score. A positive score is given pluses, a negative score minuses. For example a score of 5.6 would be represented as ++++++; a score of -2.2 would be represented as --.

The status is always either innocent or spam, depending on the score.

When virus scanning is enabled, the header X-Anti-Virus is added to messages that have been scanned. This is set to either infected or clean.

The content of an email can be changed if it’s marked as spam by SpamAssassin. For example, you may wish to prepend an email’s subject with SPAM to highlight it in your inbox. To do this, append the following code block to the end of the /etc/exim4/system_filter file:

if $h_X-Spam-Status: contains "spam"
    headers add "Old-Subject: $h_subject"
    headers remove "Subject"
    headers add "Subject: *** SPAM *** $h_old-subject"
    headers remove "Old-Subject"

5.15. Using real-time blacklists from Spamhaus

There are three lists from Spamhaus that can be used to reject email based on the sender’s IP address, namely

The Spamhaus Block List (SBL)
a list of addresses from which Spamhaus does not recommend receiving email.
The Exploits Block List (XBL)
a list of hijacked computers infected by third party exploits and viruses.
The Policy Block List (PBL)
a list of addresses that should not be sending unauthenticated email at all.

These lists are combined to form the Zen list.

The following instructions will enable use of these lists on our example domain

  1. Connect to your machine using FileZilla

  2. On the remote directory tree, navigate to /srv/

  3. In this directory, create another directory called blacklists/. This is done by clicking the right mouse button on the config/ directory, and selecting Create directory from the menu that pops up.

  4. On your local machine create a file called This is just an empty file.

  5. Once this is done, navigate to the blacklists directory on the remote file system, and select from the local file system, and upload it. Make sure that the remote file has the correct name, i.e. no extra .txt extension.

That is all that is needed to start using the Spamhaus Zen blacklist. If you’d rather use a combination of lists create one or more of the following files:

  • to enable the SBL list
  • to enable the XBL list
  • to enable the PBL list
  • to enable the combined SBL and XBL list
  • to enable the combined SBL, XBL, and PBL list

5.16. Manually blocking incoming mail from specific sources

While publicly maintained blacklists like spamhaus are much easier to rely on and lower maintenance, at some point you might find occasion to block specific email senders. Symbiosis allows blocking based on these criteria:

  • Hostname of sender, which is matched against the reverse DNS of the sender’s IP. Example entry: *
  • IP of sender, which can be a single IP or a range specified in CIDR notation (be wary of blocking too much if you use this option). Example entry:
  • Address of sender. This option may specify wildcard records, eg "*" will catch all emails from that domain. Please note this works on the "envelope from" rather than the "from" address. Example entry:

To block with one of these criteria, you can use:

  • /etc/exim4/blacklist/by_hostname for eg
  • /etc/exim4/blacklist/by_ip for
  • /etc/exim4/blacklist/by_sender for

Each entry to these files should be on a new line.

It is also possible to explicitly allow email from senders that would otherwise be blacklisted by adding entries in similarly named files under /etc/exim4/whitelist.

5.17. Rate limiting outbound email

Symbiois can now easily be configured to limit the number of outbound emails, either per-user, or per-domain. You might want to rate limit to prevent anyone taking advantage of your server, maybe using it to send out SPAM. The limit can be configured on a per-user basis with the following file :


and on a per-domain basis with the following file :


In both cases, the contents of the file should be a number, which represents the allowed limit per day. If the file is left blank, the default of 100 is applied. Senders who breach this limit will be sent an error email to explain why their message has not been sent, and discarded.

5.18. Setting an outbound IP for all email from a domain

If the domain has a config/ip file in place then the IP in that file will be used for outgoing email. This can be useful if your machine has a number of IP addresses and you’re suffering from deliverability issues. config/

5.19. Blocking email

Symbiosis allows you to blacklist email senders by:

  • email address (specific and wildcarded)
  • by IP (specific and a range)
  • by hostname (also specific or wildcarded).

Execute the following actions as root user rather than admin.

To block a specific email address, simply add the address to the file /etc/exim4/blacklist/by_sender.

The by_sender list accepts email addresses like or wildcarded ones like * to block a whole domain. Note that this blacklist is matched against the Envelope Sender address, rather than the From address.

To block by IP, add the IP address to /etc/exim4/blacklist/by_ip

The by_ip list accepts IP addresses like or ranges like This is used to blacklist by the IP address of the connecting machine.

Finally the by_hostname list accepts hostnames like, or wildcarded like * This is used to blacklist against the reverse DNS of the IP of the host connecting.

5.20. Enabling SNI for Exim and Dovecot

If you have multiple active domains with email hosted on your server, enabling SNI will allow you to use a unique SSL certificate for each. This will help avoid the "certificate mismatch" errors you may see when attempting to login to one of your email accounts.

To configure SNI support for Exim, please see this guide.

And to configure SNI support for Dovecot, please see this guide.

5.21. Configuration layout

Here is an example configuration layout for the domain All the following files are kept in /srv/

This is where individual mailboxes are defined. If this directory does not exist, then mail will not be accepted for, unless a default forwarding address or filter has been set up.
Mail will be accepted for the email address
This is where the email for will be delivered. It will be created automatically upon receipt of the first message to that address.
File containing the password for allowing him to collect his email over IMAP/POP3, and relay email using SMTP. His username is the same as his email address. See Section 5.4, “Password files” for more information.
File containing the quota for a user. The quota should a number of bytes. This can be followed by one of k, M, or G to specify kibibytes, mebibytes, or gibibytes respectively. For example 100M would be 100 mebibytes, or 104857600 bytes. See Section 5.7, “Enforcing mailbox size with quotas” for more information.
File containing either a comma-separated list of addresses, or an Exim filter. All mail addressed to will be forwarded to the list of addresses, or processed by the filter. See Section 5.9, “Forward files” for more information.
File containing a vacation message for Bob. See Section 5.10, “Vacation messages” for more information.
File containing a Sieve filter. This can be edited by the user without shell access to the server. See Section 5.8, “Server-side filtering using Sieve” for more information.
This file contains a list of aliases for a domain. The format is the local username followed by one or more spaces, and then comma separated list of email addresses which should receive the mail. See Section 5.11, “Email alias lists” for more information.
File containing either a comma-separated list of addresses, or an Exim filter. All mail addressed to the domain for local parts without directories under mailboxes will be forwarded to this address or processed by this filter. See Section 5.9, “Forward files” for more information.
If this file is present, then all email for the domain will be scanned by SpamAssassin to determine whether it is spam. If it is spam, it will be rejected. If that file begins with the word tag, mail will never be rejected, just tagged as usual.
If this file is present, then all mailboxes for this domain will have their quota determined by this file. The quota should a number of bytes. This can be followed by one of k, M, or G to specify kilobytes, megabytes, or gigabytes respectively. For example 100M would be 100 megabytes, or 100,000,000 bytes. See Section 5.7, “Enforcing mailbox size with quotas” for more information.
If this file is present, then all email for the domain will be scanned for viruses by ClamAV. If a message is determined to contain a virus, it will be rejected. If that file begins with the word tag, mail will never be rejected, just tagged.
Reject mail for this domain if the sending machine’s IP is listed in the Spamhaus Block List.
Reject mail for this domain if the sending machine’s IP is listed in the Spamhaus Exploits Block List.
Reject mail for this domain if the sending machine’s IP is listed in the Spamhaus Policy Block List.
Reject mail for this domain if the sending machine’s IP is listed in either the Spamhaus or the Exploits block lists.
Reject mail for this domain if the sending machine’s IP is listed in the Spamhaus Zen Block List, which is a combination of the Spamhaus, Exploits, and Policy block lists.