Home > Support > HOWTO List > Setting Up Email: A Postfix/Dovecot HOWTO

Setting Up Email: A Postfix/Dovecot HOWTO

Table of Contents

Mail Quick Start

Want the 5 minute email setup guide?  Use our 25Mail.st managed email hosting service.

Want the 15 minute email setup guide?  Do it on your own server. These steps will permit a user 'emailusername' to collect email sent to 'emailusername@yourdomain.com'.

  1. Setup DNS with an MX record
  2. Enable POP3 on your server
  3. useradd --create-home -shell /sbin/nologin emailusername
  4. passwd emailusername
  5. Set up your email client

If you are running an 'old-ish' distro, e.g. something pre 2010, e.g. before Ubuntu 10.4, then you will need to start enable the saslauthd service:

  1. chkconfig saslauthd on (if you are running a pre-2010 distro, e.g. before Ubuntu 10.4)
  2. /etc/init.d/saslauthd start

If you are running a newer distro then apt-get install mail-stack-delivery. That will configure Dovecot to offer SASL authentication to Postfix using a socket.

And, if you want to, let a user collect more than one email address

If you want your server to collect email for domains other than the one you ordered, you'll need to setup the destinations.

If you want the longer explanation of each of these steps, read on.  Also, you may find this chapter from the Webmin guide useful: http://swelltech.com/support/webminguide-1.0/ch11.html.

You Need an MX Record: Set Up The DNS

External email will only reach your VPS if you have an MX record set up for your domain pointing to your VPS.  Most people set their MX record to their domain name - meaning mail will be served from the same machine as your website.

Note that an MX record is required, even if yourdomainname.com resolves to your VPS's IP address (i.e. an MX is required in addition to your regular 'A' IP address record).

If you have a pre-existing email server picking up your mail, try to get your VPS email server up and running and tested before switching your MX record to point to the VPS.

pingability.com provides a very useful web based tool to check your DNS settings.  e.g. that you have a MX record.

More on DNS Configuration...

Selecting a Mail Transport Agent: Postfix It Is

This HOWTO is for setting up the Postfix server (aka Mail Transport Agent/MTA).

Make sure Postfix is running on your server.  (It should be by default on our RHEL4-based distros).  When you run ps axf you should see something like this in the output:

  319 ?        Ss     0:00 /usr/libexec/postfix/master
  326 ?        S      0:00  \_ qmgr -l -t fifo -u
 9629 ?        S      0:00  \_ pickup -l -t fifo -u

If its not running, then get it to start at boottime.  Do this via Webmin: System; Bootup and Shutdown; postfix; Start at Boottime, or via SSH: chkconfig --level 35 postfix on; /etc/init.d/postfix start.

Now you will be able to send mail from your server.  Try it with a command like this from your server: echo "test" | mail -s testsubject someemail@hotmailorwherever.com

Tip: You can send a file from a Linux command line like this:

(echo "$afilename is attached" ; cat  $afilename | uuencode $afilename) | mail -s "`echo $afilename`" youraddress@yourserver.com

My Destinations: For Which Domains Will Your Server Receive Email?

By default your mail server should accept email sent to its hostname.  Sometimes you also need it to accept email send to other domains, for example email for other domains you host on the server.

Open Webmin.  Go to Servers, Postfix Configuration, General Options.  In the "What domains to receive mail for" section, enter the domains for which you want Postfix to receive mail.  e.g. "yourdomain.com".  If you are just editing the main.cf, set virtual_mailbox_domains to the domains you need.

If email intended for users of other domains ends up at your server (for whatever reason), it will be rejected with an error message like "reason: 550 Host unknown".

Mail Users

Now we need to configure where the mail your server receives goes...

Add a Unix user.  e.g. via ssh: useradd --create-home -s /sbin/nologin emailusername; passwd emailusername.  The /sbin/nologin option will prevent the user from logging in to your server via, say, ssh.  You could also create the user via Webmin: System; Users and Groups; Create a New User.  This will be the user account that holds (stores) the emails for users until they pick them up.  It does not have to match up with any of the email@ names you will be using, but it can (and will ensure that at least emailusername@yourdomain.com works).

POP3/IMAP: Picking Up Your Email Remotely With Dovecot

One way to read your email is to log onto your VPS and use a program like pine or mail to read your emails.  But you probably want it in Outlook or something, right?  OK, so you need a POP3 (mail is deleted from the server and stored on the client) or IMAP (mail is stored on the server and sometimes cached on the client) server.  Your email client will connect to it, and pick up the email.

In this HOWTO we will be using dovecot as both our POP3 and IMAP server.  dovecot needs to be installed on your VPS. Install it with apt-get update; apt-get install dovecot-pop3d dovecot-imapd (on Debian or Ubuntu), or

yum install dovecot;systemctl enable --now dovecot
(on CentOS).This will ensure dovecot is installed and running. You may need to do further configuration to e.g. enable SSL on older distros.

Receiving Mail Using POP3 in Outlook

Now you need to configure your email client to use the POP3 protocol to pick up mail from that server.

In Outlook: Tools; Accounts; Add; Mail Server.  Enter your name; an email address (where replies go to, enter whatever address you want - it doesn't even have to be the same domain whose emails you're picking up).  Enter your mail server domain name for both the incoming (POP3) and outgoing (SMTP) servers (e.g. yourdomain.com).

For Account Name, enter the username you set up, e.g. emailusername.  Enter the password you set.  Don't tick the "Secure Password Authentication" option (it won't work and it will stop you sending emails).

At this point someone can send an email to emailusername@yourdomain.com and it should show up in your email client.  Groovy.

One User, Multiple Email Addresses (Aliases)

Say you want to pick up multiple emails addresses (e.g. info@yourdomain.com in addition to your regular email address).  In Webmin: Servers; Postfix Configuration; Mail Aliases, Create a New Alias.  Enter: Address of "info"; Alias to "Email Address" of "emailusername".  There is no need to put the @yourdomain.com in these addresses. 

After you have made this change Webmin will have added a row like info: emailusername in /etc/aliases.  If you prefer you can just directly edit the /etc/aliases file, then restart your mail server.

One Email, Multiple Recipients: Forwarding To Multiple Email Addresses (Aliases)

Want one email address (e.g. sales.yourdomain.com) to go to several different users?

In Webmin: Servers; Postfix Configuration; Mail Aliases, Create a New Alias.  Enter Address of "sales"; Alias to "Email Address" of "emailusername1,emailusername2,someotheruser@hotmail.com".  Now if you email the sales alias, the email will get sent to those three addresses addresses.

These entries will also appear in /etc/aliases like sales: emailusername1,emailusername2,someotheruser@hotmail.com.  You can edit /etc/aliases directly if you need to.

Handling Email For Multiple Email Domains

If your server is handling emails for more than one domain...  First make sure each domain's MX record points to your server.  Then make sure each of the domains  is in your Destinations/Local Domains list.

Catch-all Email Accounts: /etc/postfix/virtual

If a user mistypes an email address when they send it to you, or just guesses at a valid email address, then they will likely get an error message from your server (user does not exist).  You may wish to set up a "catch all" Address Mapping so these emails are accepted.

Go to Webmin: Servers; Postfix Configuration; Virtual Domains.  If "Domain mapping lookup tables" is not set, change it to hash:/etc/postfix/virtual.   Then go to "New Mapping".  In "Name" enter "@yourdomain.com".  In "Maps To..." use "emailusername".   i.e. the user account you set up before (vs. some email address).

The entries you create will end up in the /etc/postfix/virtual file.  You can add values to that file directly.  For example, @yourdomain.com emailusername would be added by the previous steps.

If you add entries to the /etc/postfix/virtual file via SSH (not webmin) then you may also need to run postmap /etc/postfix/virtual (to create a new virtual.db file) and restart postfix.

Note, that if you set up a catch-all email address, you will likely receive more unsolicited email.

Sending Mail From Your PC

The default Postfix install we do will let you send email to other domains through it.  It will only do this if you authenticate yourself first, i.e. use a username and password.  This is good, since otherwise spammers could use your server as an open relay.

Try this:

telnet yourserveripaddress 25
Type in:
EHLO yourdomain.com

Then check that the response code includes something like:

If you do not get the 250-AUTH line back, make sure that saslauthd is running. You can start it up with:

/etc/init.d/saslauthd start

Running chkconfig saslauthd on will make it start up by default.

Check your email client is doing SMTP authentication.  For example, in Outlook go to Tools | Accounts | <your server name> | Servers tab | Outgoing Mail Server.  Then check you have ticked "My Server Requires Authentication".  Under the Settings... button you can just leave things as is (i.e. use the same username and password).

Testing Your Email Setup

First, get a report on your domain from pingability.com.  This invaluable report will check a number of things, including whether your email server is an open relay; that it is listening on a public IP; that you have an MX DNS record; and more.  DNSReport may warn about missing reverse DNS entries.  If you need one of these, just pop in a support ticket and we will create one.  We create RDNS entries automatically for customers who do not have them every couple of weeks.

OK.  Now from Outlook try the following tests:

Send an email from your usual email account to one of the email addresses you set up on the server.  Did you get it?  A connection error when trying to receive email usually indicates dovecot is not running.  An authentication error may indicate you are not using the username and password you set up earlier.  Other problems may be caused by MX records in DNS not being correct (check via nslookup).  Or the Postfix Destinations may not list that email domain (in which case the email should bounce back to the sender).

Send an email via your new email server to one of the email addresses you set up.   Did you get it?  A connection problem could be due to your mail server listening on the localhost ( IP address vs. a public IP address.  netstat -l will tell you what services are listening on what ports and IP addresses, * means all IP addresses.

Send an email via your new email server to one of your email addresses on another server.  This checks whether you can 'relay' email.

Resolving: Proper authentication required

When you send an email from your PC through your VPS's SMTP server do you get an error message like: Relaying denied. Proper authentication required.', Port: 25, Secure(SSL): No, Server Error: 550, Error Number: 0x800CCC79?

Check you have ticked the "My Server Requires Authentication" option on your Outgoing Server section (in Outlook).

Resolving: The server does not support a SSL connection

Do you get an error message like The server does not support a SSL connection. Protocol: SMTP, Server Response: '250 HELP', Port: 25, Secure(SSL): Yes, Server Error: 250, Error Number: 0x800CCC7D?

If so, untick the "This server requires a secure connection (SSL)" option on the "Advanced" tab of your mail server properties.

Resolving: POP3 Login Problems

Can't log in to your POP3 email?

Check your /var/log/messages file.  Are you getting an error message like "ipop3d: Command stream end of file while reading line"?

This error message usually indicates your email client (Outlook) needs to be restarted.

Still can't log in?

Try talking to your pop3 server (on port 110).  It may tell you more than your Windows email client:

telnet yourserverip 110
USER emailusername
PASS yourpassword

What is the error message?

"-ERR Unable to open user's INBOX"?  There should be no file, or a file with that user's name in /var/spool/mail.  Check the file is not actually a directory (oops!).  Make sure that the file has user read/write permissions.

Installing WebMail: SquirrelMail

Do you want to send email and look at your email from a web browser?  Do you need to access email when you are away from your regular PC?  Then you may wish to setup a web based mail client.  Here is how:

Run: apt-get install squirrelmail

Squirrelmail needs an IMAP server to operate.  Otherwise you will get an error like Error connecting to IMAP server: localhost.111 : Connection refused.  So ensure that dovecot is running (see above).

Restart httpd (so it will load in /etc/httpd/conf.d/squirrelmail.conf):
/etc/init.d/xinetd restart
/etc/init.d/httpd restart

If you installed SquirrelMail onto a Debian server then you may need to add this alias line to your apache conf file: Alias /webmail/ "/usr/share/squirrelmail/"

Now browse to http://yourip/webmail/index.php and you should be at a webmail prompt.

Squirrelmail uses the server hostname in its config file and appends this to the username on outgoing email.  If you have multiple domains and want each domain to append their domain name on the From address then you will need to copy the squirrelmail directory to another location (e.g. somedomain.webmail) and modify the config file.

You can also modify the squirrelmail domain name by running /usr/share/squirrelmail/config/conf.pl

ISPs Filtering Port 25.  AKA Resolving: The message could not be sent because connecting to SMTP server example.com failed.

This error typically occurs when your email client cannot connect to the SMTP service (e.g. sendmail or postfix) on your server.

Check that sendmail is not just listening on the address.  If you followed this howto then this is likely not the problem.

The more likely problem is that your ISP (or cable modem provider, DSL provider, office network admin, your home firewall, your local PC firewall, etc) is filtering out any outgoing traffic on port 25.  Many ISPs (e.g. Earthlink) do this.  Their goal is to try and reduce spam email by forcing people to use the ISP's email server.  Some ISPs silently divert all outgoing SMTP traffic to their own SMTP server.  Other ISPs will 'null route' those packets, meaning you will just not be able to connect to your server's mail service.

You have a couple of options.  First, you can always use your ISP's email server.  It is perfectly possible to send email (with your email address) from your ISP's SMTP server.

Second: you can have your mail server listen on a port other than the one your ISP is filtering.  For example, port 2525.  To do this edit your /etc/postfix/master.cf file and after the the line:

smtp      inet  -       -       -       -       -       smtp


2525      inet  -       -       -       -       -       smtp

Then update your email client's settings to use port 2525 rather than the default port 25 when sending email.