How to Install an Email Server on your Raspberry Pi?

There are many projects that require the ability to send emails, but creating a mail server can also be a project on its own.
So, we will see the different steps of setting up an email server, be it a simple SMTP or a complete suite with webmail.

Postfix is the main service to install on Raspberry Pi to host a mail server. It’ll send and receive emails.
Then other services can be added, like Dovecot for POP/IMAP support and Roundcube can be used as webmail.

We will now learn how to install everything in this step-by-step tutorial.

If you are looking to quickly progress on Raspberry Pi, you can check out my e-book here. It’s a 30-day challenge, where you learn one new thing every day until you become a Raspberry Pi expert. The first third of the book teaches you the basics, but the following chapters include projects you can try on your own.

Prerequisites

If you want to set up an SMTP server, the requirements are almost non-existent.
A Raspberry Pi and an SMTP server that will serve as a relay is sufficient (Gmail for example).

If you want to follow the tutorial until the end, you will need:

• A Raspberry Pi: Any model should be fine, but I would recommend a Raspberry Pi 4 or at least a Raspberry Pi 3B+.
• A micro-SD card or USB key: I tend to use SD card less and less, and use this USB drive from SanDisk instead for all my experiments. But if you want to use an SD card you can, I did a benchmark of the most popular SD cards here.
• A domain name (I will use domain.com in all the steps below, don’t forget to change it).
• A static public IP address (or at least one dynamic DNS service).

Also, know that I make this tutorial on Raspberry Pi OS, so I recommend installing Raspberry Pi OS first (Lite will be enough) by following this tutorial.

I suggest you use SSH to follow this tutorial from your usual computer and copy/paste commands and configurations (there are a lot of them!). If you need help to set up SSH on your Raspberry Pi, click on the link to learn everything about this protocol and how to use it.

Security warning

Creating your secure mail server is not straightforward.
It’s easy to miss the configuration and turn your server into an open SMTP relay for the world, or get spammed over.

So be sure to follow this tutorial precisely, and then monitor the system logs to make sure that you are the only one doing the actions that occur on your server.
Setting up additional security features such as a firewall or fail2ban service is also a good idea.

DNS Configuration

IP Address

In the next steps, we will change our domain name DNS settings to use our IP address as the mail server.

If you don’t have a static public IP address, you will need to use a free dynamic DNS service like No-IP to redirect a domain to your dynamic IP address.

You’ll have to install a tool to regularly give them your current IP address, and they will redirect a domain like myserver.ddns.net to your last known IP address (more details about this here).
If you don’t have a domain name, I think that you can use this alias directly.

It’s not the perfect option for an email server because you’ll have small downtimes when your IP changes, but if you’re not too serious about your emails, it should be fine.

DNS zone configuration

Now you need to go to your domain name registrar and change these zones to match your current IP address (or your dynamic DNS provider domain name):

• MX
• pop.domain.com
• smtp.domain.com
• imap.domain.com
• mail.domain.com

MX is mandatory to receive email on your Raspberry Pi. The other ones are just easy-to-remember names for access to your emails.

Changes may take up to 24 hours before applying.
You can monitor the progress of the changes with an online tool like Network-Tools.com.
Choose “DNS” in the “Tool” dropdown, and type the domain or subdomain you want to check.

Your battle plan

If you need an overview of everything I’ll explain in this guide, here is a quick draw of everything we need:

It’s hard to put everything on the same schema without being too hard to read, but feel free to come back to this at anytime if you are a bit lost in the steps below.

Install Postfix to send emails

Now let’s move on to the main things and to the installation of Postfix.

Postfix will be the base of our mail server.
It will allow us to send and receive emails corresponding to our domain name.
In this step, we’ll learn how to send emails.

Installation

As for any tutorial, start by doing the system updates if not already done:
sudo apt update
sudo apt upgrade

You can then install the Postfix package:
sudo apt install postfix

During the installation, you’ll have to choose these two configuration options:

• The general type of mail configuration: Internet site
• System mail name: domain.com

Now we will make two changes in the configuration that has been generated:

• Open the configuration file:
  sudo nano /etc/postfix/main.cf
  If you are not used to nano, I would recommend reading this article first. I explain the basics as well as the most important shortcuts you can use in Nano.
• Disable IPv6 management:
  • Replace:
    inet_protocols = all
  • With:
    inet_protocols = ipv4
• Enter your domain name as myhostname:
  myhostname= domain.com
• If you are on a local network, most of the Internet providers don’t allow sending emails directly.
  So, you may need to add a relay host in your configuration.
  Ask your provider for the server to use as a relay:
  relayhost = smtp.yourprovider.com
  You can also use Gmail as your relay (username and password will be required in your configuration file).
• Save and exit (CTRL+O, Enter, CTRL+X).
• Restart Postfix:
  sudo service postfix restart

At this point, the server should start properly without startup errors.
If this is not the case, look to solve these problems before continuing.

Are you a bit lost in the Linux command line? Check this article first, for the most important commands to remember, and a free downloadable cheat sheet so you can have the commands at your fingertips.

Testing

We’ll now make our first test by sending an email from the Raspberry Pi.

Telnet

For this test, we’ll use telnet to connect to postfix.

• Install telnet:
  sudo apt-get install telnet
• Connect to the SMTP server:
  telnet localhost 25
• Enter this series of commands:
  • ehlo
  • mail from: you@domain.com
  • rcpt to: user@mail.com
  • data
  • Subject: test
  • Test
  • .
  • quit
• This commands sequence will create an email and send it to user@mail.com (external email address).

Here is the full trace:

pi@raspberrypi:~ $ telnet localhost 25
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 domain.com ESMTP Postfix (Raspbian)
ehlo domain.com
250-domain.com
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250-STARTTLS
250-ENHANCEDSTATUSCODES
250-8BITMIME
250-DSN
250 SMTPUTF8
mail from: me@domain.com
250 2.1.0 Ok
rcpt to: youremail@gmail.com
250 2.1.5 Ok
data
354 End data with <CR><LF>.<CR><LF>
Subject: test
Test
.
250 2.0.0 Ok: queued as 44EAE1FE54
quit
221 2.0.0 Bye

Mailutils

If you are looking for a most friendly way to do this, you can install mailutils to use the mail command.

• Install mailutils:
  sudo apt install mailutils
• Send a test email with the mail command:
  echo 'Test' | mail -s "Test mail command" you@gmail.com

In both cases, you can follow the email sending in this log file: /var/log/mail.log

Debugging

Either way, you can check the log file /var/log/mail.log to see what happens if you didn’t receive the email.
If everything works correctly, you should see something like this:
Jul 1 04:14:32 raspberrypi postfix/local[5433]: 734AA1FF96: to=, relay=local, delay=0.09, delays=0.01/0.04/0/0.04, dsn=2.0.0, status=sent (delivered to mailbox)

Receive emails with Postfix

Now it’s time to edit our Postfix configuration to receive emails.

Configuration

We’ll do this by using the Maildir mailboxes format.
Maildir is a safe and easy way to store emails: each mailbox is a directory, and each email is a file.

• Edit the configuration file:
  sudo nano /etc/postfix/main.cf
• Add these lines at the end of the file:
  home_mailbox = Maildir/
mailbox_command =
  This configuration will tell Postfix to create a Maildir folder for each system user.
  This folder will now host your new incoming emails.

Now we need to create the Maildir folder template by following these steps:

• Install this packages:
  sudo apt install dovecot-common dovecot-imapd
• Create folders in the template directory:
  sudo maildirmake.dovecot /etc/skel/Maildir
sudo maildirmake.dovecot /etc/skel/Maildir/.Drafts
sudo maildirmake.dovecot /etc/skel/Maildir/.Sent
sudo maildirmake.dovecot /etc/skel/Maildir/.Spam
sudo maildirmake.dovecot /etc/skel/Maildir/.Trash
sudo maildirmake.dovecot /etc/skel/Maildir/.Templates

These templates will be used when you add new users on your Raspberry Pi.
But for those already existing, you have to do it manually.

For example, you have to run these commands for pi:
sudo cp -r /etc/skel/Maildir /home/pi/
sudo chown -R pi:pi /home/pi/Maildir
sudo chmod -R 700 /home/pi/Maildir

Testing

You can now repeat the same kind of test as before, but put the user pi in the receiver:
echo "Test" | mail -s "Test" pi@domain.com

And then check that the mail has arrived in the Maildir folder:

pi@raspberrypi:~ $ cat /home/pi/Maildir/new/1625109614.Vb302I205f1M127492.raspberrypi
 Return-Path: 
 X-Original-To: pi@rpi.tips
 Delivered-To: pi@rpi.tips
 Received: by rpi.tips (Postfix, from userid 1000)
         id 1CC5A205F2; Thu,  1 Jul 2021 04:20:14 +0100 (BST)
 Subject: Test mail command
 To: pi@rpi.tips
 X-Mailer: mail (GNU Mailutils 3.5)
 Message-Id: 20210701032014.1CC5A205F2@rpi.tips
 Date: Thu,  1 Jul 2021 04:20:14 +0100 (BST)
 From: pi@raspberrypi
 Test

You should have only one mail in the new folder, use tab auto-completion to find it.
As you can see the return path address is not correct, you have to change your hostname to fix this:
sudo hostname domain.com
More details here on how to change the hostname on a Raspberry Pi (there is more to know).

But we have reached our goal for this step.
We received emails sent to our domain.

Secure the mail server

As I said at the beginning, there are some options to put in place to secure a minimum of the webserver.

• Edit your configuration file:
  sudo nano /etc/postfix/main.cf
• Add these lines at the end of the file:
  smtpd_helo_restrictions =
permit_mynetworks =
permit_sasl_authenticated =
reject_invalid_helo_hostname =
reject_non_fqdn_helo_hostname =
reject_unknown_helo_hostname =
check_helo_access =
hash:/etc/postfix/helo_access =

• This configuration will limit SMTP usage to the local network and reject people saying that they are from your domain name.
• Create the helo_access file:
  sudo nano /etc/postfix/helo_access
In this file, we need to put the list of domain names we want to block.
• Paste these lines into it:
  X.X.X.X REJECT
domain.com REJECT
smtp.domain.com REJECT
mail.domain.com REJECT
  Replace X.X.X.X with your public IP address.
• Restart postfix daemon:
  sudo service postfix restart

Having a certain set of good practices in place to improve the overall security of the Raspberry Pi is also a good idea, especially if you are using this server for important email.
You can read my 17 security tips for Raspberry Pi here, and I also recommend setting up a backup system, as explained in this article.

Install Dovecot to allow POP and IMAP connections

We now have a functional and secure mail server.
So, we will move on to the next part, which is to make this mail server accessible to POP and IMAP clients via SASL authentication.

As you may have noticed, we already installed Dovecot in the previous step to create Maildir folders.
The only thing left to do is to finalize the configuration.

Configuration

• Open the Dovecot configuration file:
  sudo nano /etc/dovecot/dovecot.conf
• Remove IPV6 support:
  • Replace:
    #listen = *, ::
  • With:
    listen = *
• Open the Dovecot mail configuration file:
  sudo nano /etc/dovecot/conf.d/10-mail.conf
• Edit the Maildir folder:
  • Replace:
    mail_location = mbox:~/mail:INBOX=/var/mail/%u
  • With:
    mail_location = maildir:~/Maildir
• Open the Dovecot master configuration file:
  sudo nano /etc/dovecot/conf.d/10-master.conf
• Tell Dovecot to listen for SASL authentification:
  • Comment all lines from the default service auth paragraph (add # before each line).
  • Add these lines at the end of the file:
    service auth {
unix_listener /var/spool/postfix/private/auth {
mode = 0660
user = postfix
group = postfix
}
}
• Open the Dovecot auth configuration file:
  sudo nano /etc/dovecot/conf.d/10-auth.conf
• Allow plaintext auth.
  • Uncomment and edit this line:
    #disable_plaintext_auth = yes
  • To become this one:
    disable_plaintext_auth = no
• Edit this line too:
  auth_mechanisms = plain login
• Edit the Postfix configuration file:
  sudo nano /etc/postfix/main.cf
• Tell Postfix to use SASL (add these lines):
  smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_sasl_auth_enable = yes
• Restart Dovecot and Postfix:
  sudo service postfix restart
sudo service dovecot restart

Keep an eye on the log files, and you can use “sudo service X status” to check that the service is running correctly. As I told you previously, a misconfiguration can happen fast. But we’ll do another test now to make sure everything is good.

Testing

To test that SASL authentication works well, we will create a test user and try to connect to the mail server with it.

User creation

Create a new user with a login test and the password you want:
sudo adduser test

Answer the questions related to the password (and remember it). The other questions are not mandatory (press Enter to skip them).

Get the encoded password

We need to get our password in a base64 encoded format.
You can get it with this command:
printf '\0%s\0%s' '[LOGIN]' '[PASSWORD]' | openssl base64

Replace [LOGIN] and [PASSWORD] in this command with the ones you choose during the adduser command.
In my case (test/password), the string displayed is AHRlc3QAcGFzc3dvcmQ=.

Log in

We can now retry a connection with telnet by specifying this string for identification.
The only change is that we need to use the AUTH PLAIN command to log in:
telnet localhost 25
ehlo domain.com
AUTH PLAIN

You can quit after this if you get the “Authentication successful” message, or send another test email like the first time if you have any doubt.
Here is the full trace:

pi@raspberrypi:~ $ telnet localhost 25
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 domain.com ESMTP Postfix (Raspbian)
ehlo domain.com
250-domain.com
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250-STARTTLS
250-AUTH PLAIN LOGIN
250-ENHANCEDSTATUSCODES
250-8BITMIME
250 DSN
AUTH PLAIN AHRlc3QAcGFzc3dvcmQ=
235 2.7.0 Authentication successful
mail from: me@domain.com
250 2.1.0 Ok
rcpt to: youremail@gmail.com
250 2.1.5 Ok
data
354 End data with <CR><LF>.<CR><LF>
Subject: test
Test
.
250 2.0.0 Ok: queued as 44EAE1FE54
quit
221 2.0.0 Bye

Enable IMAPS

Dovecot allows us to connect with IMAP (telnet localhost 143).
But we now need to enable TLS for IMAP on the port 993.

• Edit the Dovecot master configuration file:
  sudo nano /etc/dovecot/conf.d/10-master.conf
• Enable listener on the port 993:
  The configuration should look like this (there are a few lines to uncomment):
  service imap-login {
inet_listener imap {
port = 143
}
inet_listener imaps {
port = 993
ssl = yes
}
}
• Then edit the SSL configuration file:
  sudo nano /etc/dovecot/conf.d/10-ssl.conf
• Make sure SSL is enabled at the beginning of the file:
  ssl = yes
• The certificate locations should also be uncommented:
  ssl_cert = </etc/dovecot/private/dovecot.pem
ssl_key = </etc/dovecot/private/dovecot.pem
• Finally, restart Dovecot server:
  sudo service dovecot restart

You can now check that your IMAPS server is working, with this command:
openssl s_client -connect localhost:993

The login syntax is:
a login [LOGIN] [PASSWORD]

The full trace should look something like this:

* OK [CAPABILITY IMAP4rev1 LITERAL+ SASL-IR LOGIN-REFERRALS ID ENABLE IDLE AUTH=PLAIN AUTH=LOGIN] Dovecot ready.
a login pi password
a OK [CAPABILITY IMAP4rev1 LITERAL+ SASL-IR LOGIN-REFERRALS ID ENABLE IDLE SORT SORT=DISPLAY THREAD=REFERENCES THREAD=REFS THREAD=ORDEREDSUBJECT MULTIAPPEND URL-PARTIAL CATENATE UNSELECT CHILDREN NAMESPACE UIDPLUS LIST-EXTENDED I18NLEVEL=1 CONDSTORE QRESYNC ESEARCH ESORT SEARCHRES WITHIN CONTEXT=SEARCH LIST-STATUS BINARY MOVE SPECIAL-USE] Logged in
b select inbox
* FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
* OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft \*)] Flags permitted.
* 3 EXISTS
* 0 RECENT
* OK [UNSEEN 1] First unseen.
* OK [UIDVALIDITY 1536038369] UIDs valid
* OK [UIDNEXT 4] Predicted next UID
b OK [READ-WRITE] Select completed (0.000 + 0.000 secs).
b logout
* BYE Logging out
b OK Logout completed (0.000 + 0.000 secs).
closed

You can now connect to your IMAP server from any client on the LAN.
If you want to access your server from anywhere, don’t forget to open the needed ports in your router firewall.

Set up Roundcube to add a webmail access

Most of the work is done, but we will push a little more and add a Webmail server to our mail server on Raspberry Pi.
Roundcube is a modern free and open-source webmail software.

The big advantage of Roundcube compared to other webmails is that it’s available directly in the Debian and therefore Raspberry Pi OS repositories.

If you started from a blank Raspberry Pi OS, you would need to install a MySQL server first (MariaDB).

MySQL server

If you don’t have one yet, you need to install a MySQL server to store the Roundcube database:
sudo apt install mariadb-server

Then you need to follow these steps to set a root password, and create a Roundcube user:

• Connect with root (we need sudo because only root can access):
  sudo mysql -uroot
• Set the root password:
  use mysql;
UPDATE user SET password=PASSWORD('YourPassword'), plugin='' WHERE User='root' AND Host = 'localhost';
FLUSH PRIVILEGES;
  Don’t forget to replace “YourPassword” with a secure password.
• Create a new user for Roundcube:
  CREATE USER 'roundcube'@'localhost' IDENTIFIED BY 'password';
  Replace “password” with your chosen password
• Create the Roundcube database.
  CREATE DATABASE roundcubemail;
• Give all privileges to the Roundcube user on the Roundcube database:
  GRANT ALL PRIVILEGES ON roundcubemail.* to 'roundcube'@'localhost';
• Quit the MySQL console:
  FLUSH PRIVILEGES;
quit

Your database server is ready, move to the next step.

Roundcube

To install it, enter the following command:
sudo apt install roundcube roundcube-plugins

This will also automatically install all other dependencies (mainly Apache, PHP, and MySQL client).

Again, the installation wizard will ask you these questions about your MySQL server:

• Configure database with dbconfig-common: yes.
• MySQL application password for Roundcube: your Roundcube user password.
• Database administrator password: your MySQL root password.

Note: I got a connection error at this step, but when choosing "retry" I could edit all settings including the database name, and it was OK after that.

Now edit the apache configuration for Roundcube to enable the web app:
sudo nano /etc/apache2/conf-enabled/roundcube.conf

Uncomment the first line:
Alias /roundcube /var/lib/roundcube

Then restart your web server:
sudo service apache2 restart
And go to http://[RASPBERRY-IP]/roundcube to see the web interface.

If you get any error, you can restart the installation wizard with this command:
sudo dpkg-reconfigure roundcube-core
It will also give you the chance to set a default server if you prefer.

You can now log in with your credentials created in the previous step, or with the account “pi”.
Enjoy your webmail now, and remember that it is possible to add many plugins on RoundCube to extend its features.

Logs and configuration file summary

So we saw how to set up a full mail server on Raspberry Pi.
If you have had any errors, or want to go further, here is the summary of the file locations.

Postfix

In this tutorial, we are using Postfix to send and receive emails, it’s the core of the mail server.

Configuration

• /etc/postfix/main.cf: Main configuration for Postfix.
• /etc/postfix/master.cf : Processes configuration for Postfix.

Log files

• / var/log/mail.log: Here you can see all mail traces, and errors if there are any.

Dovecot

We installed Dovecot to manage IMAP connections with a SASL security layer.

Configuration

• /etc/dovecot/dovecot.conf: The main configuration of Dovecot.
• /etc/dovecot/conf.d/: This subfolder contains several files with each part of the configuration to easily know where the option you’re looking for is.

Log files

• /var/log/syslog: Dovecot doesn’t have a specific log file, it’s using the main syslog file.

Apache

Apache is used in this tutorial to run Roundcube.
Normally you shouldn’t need to change something unless Roundcube is not accessible at all.

Configuration

• /etc/apache2/apache2.conf: The main configuration file for apache2.
• /etc/apache2/conf-enabled/: Here you will find the configuration for some Apache services (like Roundcube.conf).
• /etc/apache2/sites-enabled/: Here you will find the configuration for any Apache website.

Log files

• /var/log/apache/error.log: If you get any errors with Apache, you can find them here.

Roundcube

And finally, we installed Roundcube to add webmail to our mail server.

Configuration

• /etc/roundcube/config.inc.php: Here is the main configuration file for Roundcube.

Log files

• /var/log/roundcube/errors: If you get some issue with Roundcube, you’ll find the errors in this file.

Conclusion

And here we are at the end of this tutorial.
You have learned to set up a complete mail server with:

• Postfix for transport.
• Dovecot for secure authentication.
• Roundcube for web access to your emails.

As you may have noticed, it’s not a simple thing to set up. There are a lot of configuration options, and it can be a lot of work to put that in place at home.

I think in most cases, the first part with Postfix is the one that will interest you.
You are going to be able to send emails from your different projects, but not necessarily to set up all the other steps.

In any case, if you really need to install everything, you know how to do.

Additional Resources

Not sure where to start?
Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.
Watch the Raspberry Pi Bootcamp course now.

Master your Raspberry Pi in 30 days
Don’t want the basic stuff only? If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.
Download the e-book.

VIP Community
If you just want to hang out with me and other Raspberry Pi fans, you can also join the community. I share exclusive tutorials and behind-the-scenes content there. Premium members can also visit the website without ads.
More details here.

Need help building something with Python?
Create, understand and improve any Python script for your Raspberry Pi.
Learn the essentials, step-by-step, without losing time understanding useless concepts.
Get the e-book now.

You can also find all my recommendations for tools and hardware on this page.