There are many projects that require the ability to send email, but creating a mail server can also be a project in itself. then, we will see the different steps to configure an email server, whether it is a simple smtp or a complete suite with webmail.
postfix is the main service to install on raspberry pi to host a mail server. will send and receive emails.other services can then be added, such as dovecot for pop/imap support and roundcube can be used as webmail.
now we will learn how to install everything in this step by step tutorial.
if you want to make rapid 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 subsequent chapters include projects you can try on your own.
requirements
If you want to set up an smtp server, the requirements are almost non-existent. a raspberry pi and an smtp server that serves as a relay is enough (gmail, for example).
If you want to follow the tutorial to 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 card -sd or usb key: I tend to use the sd card less and less, and instead use this sandisk usb drive for all my experiments. but if you want to use sd card you can. I benchmarked the most popular sd cards here.
- a domain name (I’ll use domain.com in all the steps below, don’t forget to change it).
- a static public ip address (or at least a dynamic dns service).
Also, know that I made this tutorial on raspberry pi os, so I recommend installing raspberry pi os (lite will suffice) first by following this tutorial.
I suggest you use ssh to follow this tutorial from your regular computer and copy/paste commands and settings (there are many!). If you need help setting up ssh on your raspberry pi, click the link to learn all about this protocol and how to use it.
security warning
Creating your secure mail server is not easy. it’s easy to bypass the settings and turn your server into an open smtp relay for the world, or get spammed.
so make sure you follow this tutorial precisely and then check your system logs to ensure that you are the only one performing the actions that occur on your server. configure additional security features such as a firewall or fail2ban service is also a good idea.
dns configuration
ip address
In the next few steps, we will change our domain name’s dns settings to use our ip address as the mail server.
if you don’t have a static public ip address, you’ll need to use a free dynamic dns service like no-ip to redirect a domain to your dynamic ip address.
You’ll need to install a tool to regularly provide them with your current ip address, and they’ll redirect a domain like myserver.ddns.net to your last known ip address (more on that here). If you don’t I don’t have a domain name, I think you can use this alias directly.
It’s not the perfect choice for an email server because you’ll have a little downtime when you change your ip, but if you’re not too serious about your emails, you should be fine.
dns zone configuration
You now need to go to your domain name registrar and change these zones to match your current ip address (or your dynamic dns provider’s domain name):
- mx
- pop.domain.com
- smtp.domain.com
- imap.domain.com
- mail.domain.com
mx is required to receive email on your raspberry pi. the others are just easy-to-remember names to access your emails.
Changes may take up to 24 hours to take effect. you can monitor the progress of the changes with an online tool like network-tools.com. choose “dns” from the “tool” dropdown and type in the domain or subdomain you want. I want to check.
your battle plan
If you need an overview of everything I’ll cover in this guide, here’s a quick rundown of everything we need:
It’s hard to put everything on the same schematic without it being too hard to read, but feel free to come back to this anytime if you’re a bit lost in the steps below.
install postfix to send emails
Now let’s get down to the basics and install 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 will learn how to send emails.
installation
As for any tutorial, start by doing the system upgrades if you haven’t done them already: sudo apt upgradesudo apt upgrade
You can then install the Postfix package:sudo apt install postfix
During the installation, you will have to choose these two configuration options:
- the general type of mail settings: internet site
- system mail name: domain.com
Now we will make two changes to the configuration that has been generated:
- open the configuration file:sudo nano /etc/postfix/main.cfif 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
- con:inet_protocols = ipv4
At this point, the server should boot successfully with no boot errors. if this is not the case, try to fix these issues before continuing.
are you a bit lost in the linux command line? check out 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.
test
Now we will do our first test by sending an email from the raspberry pi.
telnet
for this test, we will use telnet to connect to postfix.
- install telnet:sudo apt-get install telnet
- connect to 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
- .
- exit
here is the full trace:
mail utilities
if you’re looking for the friendliest 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 command mail:echo ‘test’ | mail -s “test mail command” you@gmail.com
In both cases, you can track the email delivery in this log file: /var/log/mail.log
debug
Either way, you can check the /var/log/mail.log log file to see what happens if you didn’t receive the email.If everything works fine, 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 in the mailbox)
receive emails with suffix
now it’s time to edit our postfix configuration for receiving emails.
settings
We will do this using the maildir mailbox format.maildir is a safe and easy way to store emails: each mailbox is a directory and each email is a file.
- edit the config file:sudo nano /etc/postfix/main.cf
- add these lines to the end of the file:home_mailbox = maildir/mailbox_command =this setting will tell postfix to create a maildir folder for each user on the system. this folder will now house your new incoming emails.
now we need to create the maildir folder template by following these steps:
- Install these packages:sudo apt install dovecot-common dovecot-imapd
- create folders in template directory:sudo maildirmake.dovecot /etc/skel/maildirsudo maildirmake.dovecot /etc/ skel /maildir/.draftssudo maildirmake.dovecot /etc/skel/maildir/.sentsudo maildirmake.dovecot /etc/skel/maildir/.spamsudo maildirmake.dovecot /etc/skel/maildir/.trashsudo maildirmake.dovecot /etc/skel/ maildir /.templates
These templates will be used when you add new users on your raspberry pi. but for the ones that already exist, you have to do it manually.
for example, you should run these commands for pi:sudo cp -r /etc/skel/maildir /home/pi/sudo chown -r pi:pi /home/pi/maildirsudo chmod -r 700 /home/ pi/ maildir
test
You can now repeat the same type of test as before, but put the user pi on the receiver:echo “test” | mail -s “test” pi@domain.com
and then verify that the mail has arrived in the maildir folder:
you should have only one mail in the new folder, use tab autocomplete to find it.as you can see the return path address is not correct, you need to change your hostname to fix this :sudo hostname domain.commore details here on how to change the hostname on a raspberry pi (there’s more to know).
but we have reached our goal for this step. we receive emails sent to our domain.
secure the mail server
As I said at the beginning, there are some options to implement to secure a minimum of the web server.
- edit your config file: sudo nano /etc/postfix/main.cf
- add these lines to 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 setting will limit the use of smtp to the local network and will reject people claiming to be 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 rejecteddomain.com rejectedsmtp.domain.com rejectedmail.domain.com rejectedreplace x.x.x.x with your address public ip.
- restart postfix daemon: sudo service postfix restart
Having a certain set of best practices 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 Raspberry Pi Security Tips 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’ll 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 finish the configuration.
settings
- open dovecot config file: sudo nano /etc/dovecot/dovecot.conf
- remove ipv6 support:
- replace:#listen = *, ::
- with:listen = *
- replace:mail_location = mbox:~/mail:inbox=/var/mail/%u
- with:mail_location = maildir:~/maildir
- comment out all lines of the default service authentication paragraph (add # before each line).
- add these lines to the end of the file: service authentication {unix_listener /var/spool /postfix /private/auth {mode=0660user=postfixgroup=postfix}}
- uncomment and edit this line:#disable_plaintext_auth = yes
- to become this:disable_plaintext_auth = no
Keep an eye on the log files and you can use “sudo service x status” to verify that the service is running properly. As I told you before, misconfiguration can happen quickly. but we will do another test now to make sure everything is ok.
Testing
To test that sasl authentication works fine, we’ll create a test user and try to connect to the mail server with it.
user creation
create a new user with a test login and password of your choice: sudo adduser test
answer the questions related to the password (and remember it). the other questions are not required (press enter to skip them).
get encrypted password
we need to get our password in a base64 encoded format. you can get it with this command: printf ‘%s%s’ ‘[login]’ ‘[password]’ | open base64
replace [login] and [password] in this command with whatever you chose during the adduser command. in my case (test/password), the string displayed is ahrlc3qacgfzc3dvcmq=.
log in
we can now retry a telnet connection by specifying this string for identification. the only change is that we need to use the auth plain command to login:telnet localhost 25ehlo domain.comauth plain
You can exit after this if you get the “authentication successful” message, or send another test email like the first time if you have any questions. here is the full trace:
enable maps
dovecot allows us to connect with imap (telnet localhost 143).but now we need to enable tls for imap on port 993.
- edit the dovecot master config file: sudo nano /etc/dovecot/conf.d/10-master.conf
- enable the listener on port 993: the config should look like like this (there are a few lines to uncomment): service imap-login {inet_listener imap {port = 143}inet_listener imaps {port = 993ssl = yes}}
- then edit the ssl config file:sudo nano /etc /dovecot/conf.d/10-ssl.conf
- make sure ssl is enabled at the beginning of the file:ssl = yes
- certificate locations should also not be commented out: ssl_cert = </etc/dovecot/private/dovecot.pemssl_key = </etc/dovecot/private/dovecot.pem
- finally, restart the dovecot server: sudo service dovecot restart
You can now verify that your imaps server is up and running, with this command: openssl s_client -connect localhost:993
login syntax is: a login [login] [password]
the full trace should look like this:
now you can 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 necessary ports in your router’s firewall.
configure roundcube to add webmail access
Most of the work is done, but we’ll push a little harder and add a webmail server to our mail server on raspberry pi. roundcube is free and open source modern webmail software.
the great advantage of roundcube compared to other webmails is that it is available directly in the debian and therefore raspberry pi os repositories.
if you started from a blank raspberry pi OS, you will first need to install a mysql server (mariadb).
mysql server
if you don’t already have one, 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 root password: use mysql; update password set by user = password(‘yourpassword’) , plugin=” where user=’root’ and host = ‘localhost’;remove privileges;don’t forget to replace “yourpassword” with a strong 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 the roundcubemail database;
- grant all privileges to the roundcube user on the database from roundcube: grant all privileges on roundcubemail.* to ’roundcube’@’localhost’;
- exit console mysql:purge privileges;exit
Your database server is ready, go to the next step.
round cube
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 the database with dbconfig-common: yes.
- mysql application password for roundcube: your roundcube user password.
- administrator password from the database: your mysql root password.
now edit the apache configuration for roundcube to enable the web application: 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-coreIt 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 “pi” account. enjoy your webmail now and remember many plugins can be added in roundcube to extend its features.
configuration file summary and logs
then we saw how to set up a full mail server on raspberry pi. If you’ve run into any errors or want to continue, here’s the summary of the file locations.
postfix
In this tutorial, we are using postfix to send and receive emails, it is the core of the mail server.
settings
- /etc/postfix/main.cf: main configuration for postfix.
- /etc/postfix/master.cf: process configuration for postfix.
log files
- / var/log/mail.log – Here you can see all mail traces and errors, if any.
dovecote
we installed dovecot to manage imap connections with a sasl security layer.
settings
- /etc/dovecot/dovecot.conf – The main dovecot configuration.
- /etc/dovecot/conf.d/ – This subfolder contains several files with each part of the configuration for easily know where the option you are looking for is.
log files
- /var/log/syslog: dovecot does not have a specific log file, it is using the main syslog file.
apache
apache is used in this tutorial to run roundcube. normally, you shouldn’t need to change anything unless roundcube can’t be accessed.
settings
- /etc/apache2/apache2.conf – the main apache2 configuration file.
- /etc/apache2/conf-enabled/ – here you will find the configuration of 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.
round cube
and finally, we install roundcube to add webmail to our mail server.
settings
- /etc/roundcube/config.inc.php – Here is the main roundcube config file.
log files
- /var/log/roundcube/errors – If you have any problems with roundcube, you will find the errors in this file.
conclusion
and here we are at the end of this tutorial. you have learned how to set up a full 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 an easy thing to set up. there are many configuration options, and it can be a lot of work to implement them at home.
I think in most cases, the first part with postfix is the one you’ll be interested in. you will be able to send emails from your different projects, but not necessarily to set up all the other steps.
Anyway, if you really need to install everything, you already know how to do it.
raspberry pi resources
Not sure where to start?Understand everything about the Raspberry Pi, stop looking for help all the time, and finally enjoy completing your projects. watch the raspberry pi bootcamp course now.master your raspberry pi in 30 daysdon’t want just the basics? If you are looking for the best tips to become a Raspberry Pi expert, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides. download the e-book. vip communityif you just want to hang out with me and show your support, you can also join the patreon community. I share behind the scenes content there and give you early access to my content. You will also receive recognition when you join. more details here. step, without wasting time understanding useless concepts. get the e-book now. you can also find all my recommendations for tools and hardware on this page.