Raspberry Pi Email Server Part 1: Postfix

Postfix Logo

This is the first part of a five part tutorial that will show you how to install a full featured email server on your Raspberry Pi. This tutorial covers Postfix, the Mail Transfer Agent.

The parts are:
The Introduction & Contents Page (read first)
Raspberry Pi Email Server Part 1: Postfix
Raspberry Pi Email Server Part 2: Dovecot
Raspberry Pi Email Server Part 3: Squirrelmail
Raspberry Pi Email Server Part 4: Spam Detection with Spamassassin
Raspberry Pi Email Server Part 5: Spam Sorting with LMTP & Sieve

Installing Postfix

Note: While you are setting up the mail server on the Pi, it’s a good idea to turn off port forwarding rules for email to the Pi in your router’s firewall. If you don’t have any port forwarding rules now, that’s great, don’t worry – I’ll prompt you to set them up later.

First, log into your Pi with a SSH session and install postfix:

sudo apt-get update
sudo apt-get install postfix

You will see a menu with some choices. Select “Internet Site” and then set the mail name to your domain name, not including www. (e.g. samhobbs.co.uk).

The setup script will then do some automatic configuration for you. The output will look something like this:

Selecting previously unselected package postfix.                                              
(Reading database ... 67653 files and directories currently installed.)                       
Unpacking postfix (from .../postfix_2.9.6-2_armhf.deb) ...                                    
Processing triggers for man-db ...
Setting up postfix (2.9.6-2) ...
Adding group `postfix' (GID XXX) ...
Adding system user `postfix' (UID XXX) ...
Adding new user `postfix' (UID XXX) with group `postfix' ...
Not creating home directory `/var/spool/postfix'.
Creating /etc/postfix/dynamicmaps.cf
Adding tcp map entry to /etc/postfix/dynamicmaps.cf
Adding sqlite map entry to /etc/postfix/dynamicmaps.cf
Adding group `postdrop' (GID XXX) ...
setting myhostname: samhobbs
setting alias maps
setting alias database
changing /etc/mailname to samhobbs.co.uk
setting myorigin
setting destinations: samhobbs.co.uk, samhobbs, localhost.localdomain, localhost
setting relayhost: 
setting mynetworks: [::ffff:]/104 [::1]/128
setting mailbox_size_limit: 0
setting recipient_delimiter: +
setting inet_interfaces: all
/etc/aliases does not exist, creating it.
WARNING: /etc/aliases exists, but does not have a root alias.

You can edit all of this later.

You may also get some warnings like this:

postmulti: warning: inet_protocols: disabling IPv6 name/address support: Address family not supported by protocol

IPv6 is a new type of IP address that was introduced because we’re running out of the “old” IPv4 addresses. Not many ISPs support IPv6 yet, so you probably don’t need it. Unless you fix the warning, you’ll see it every time.

Change directory into the postfix configuration folder:

cd /etc/postfix/

Edit /etc/postfix/main.cf with your favourite command line text editor (e.g. sudo nano main.cf) and add inet_protocols = ipv4 to the end of the file.

Now is also a good time to check that your hostname is specified properly in /etc/postfix/main.cf. The setup script takes the hostname of the server and uses that, but it may not be in the right format, i.e. “samhobbs” instead of “samhobbs.co.uk”. Find the line that begins myhostname = and make sure it is your fully qualified domain name. This is important because your server will use this to talk to other mail servers, and some will reject your emails if you don’t use a fully qualified domain name to say hi! This is covered in more detail in the helo access restrictions later.

Restart postfix and you shouldn’t see the warnings any more:

sudo service postfix restart

Testing and Configuration

Before you start, it’s probably worth backing up the configuration files in their current state. This way, you’ll have something to compare to if you’re ever trying to work out which bits were defaults and which bits you changed yourself:

cd /etc/postfix
sudo cp main.cf main.cf.BAK
sudo cp master.cf master.cf.BAK

Mailbox Setup

There are a couple of different types of mailbox you can use, I’ve chosen to use a “Maildir” rather than “mbox” configuration. For users with “real” UNIX accounts on the system (like the one you’re using to log in), Maildir creates a folder in the user’s home directory and places emails inside it, one file for each email.

I prefer this to the alternatives, because it’s easier to see and understand: you can rummage around in your home folder and see all your emails as individual files.

To tell Postfix to use the Maildir format, add the following lines to /etc/postfix/main.cf:

home_mailbox = Maildir/
mailbox_command =

If there's already a line with mailbox_command, comment it out by adding a # at the start of the line.

We also need to create the mail directory and its subfolders for existing users, and add some things to /etc/skel (the template for new users) so that if you create a new account this will be done automatically.

These commands are part of Dovecot, so first we need to install it:

sudo apt-get update
sudo apt-get install dovecot-common dovecot-imapd

You will get a lot of output: some other dovecot packages will automatically be installed and the config files will be created. You will also see some errors – don’t worry about those for now, I’ll explain how to deal with them in part 2, later.

Now we can create those mail folders. Run the following commands to create the template files:

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

Next, copy the files over to existing users’ home directories, and change the ownership and permissions for privacy (replace USER with the username you are doing this for, and repeat for all existing usernames):

sudo cp -r /etc/skel/Maildir /home/USER/
sudo chown -R USER:USER /home/USER/Maildir
sudo chmod -R 700 /home/USER/Maildir

Initial Testing

Now, the best way to test Postfix during configuration is to use Telnet, because it is such a simple way of communicating between programs and there’s less to go wrong and get confused about.

First, install telnet:

sudo apt-get install telnet

Now, still inside the SSH session to your pi, type this command. It will connect you to port 25 on the Pi:

telnet localhost 25

You can now test sending an email using SMTP. Here are the steps:

  1. send an ehlo command to tell the server who you are, and it will tell you its capabilities
  2. use the mail from command to say who the email is from. If you are sending it from an address that exists on the server, you needn’t include the domain name (i.e. user instead of user@yourdomain.com)
  3. use the rcpt to command to tell the server where to send the email
  4. Use the data command to tell the server that you’re about to start giving it the message you want to send
  5. Type Subject: YOUR SUBJECT then enter to set a subject
  6. Type the body of your email. Once you’re done, press ENTER, then ., then ENTER again.
  7. Type quit to exit

Here’s an example:

telnet localhost 25
Connected to localhost.
Escape character is '^]'.
220 samhobbs.co.uk ESMTP Postfix (Debian/GNU)
ehlo foobar
250-SIZE 10240000
250 DSN
mail from: me        
250 2.1.0 Ok
rcpt to: me@outsideemail.com
250 2.1.5 Ok
354 End data with <CR><LF>.<CR><LF>
Subject: test
This is a test email
250 2.0.0 Ok: queued as A639C3EE6D
221 2.0.0 Bye

Some Access Restrictions

Add the following to /etc/postfix/main.cf to restrict who can send emails to external mail servers:

smtpd_recipient_restrictions =

Reload postfix:

sudo service postfix reload
  • Line 1 begins the list of restrictions.
  • Line 2 permits users who have authenticated with Simple Authentication and Security Layer (SASL) to send email to any destination (this is part of the Dovecot config in Part 2, later).
  • Line 3 will let users send emails to any destination if they have connected from an IP address defined in mynetworks.
  • Line 4 will reject the email if none of the above conditions have been met unless the “rcpt to” address is one of the addresses that your server is accepting email to (as defined in main.cf with the mydestination parameter).

In its present state, the email server will allow you to send external emails because the connection is originating from the Pi itself (you are logged in via SSH) and not an unknown computer. Addresses of “trusted” computers are listed under the mynetworks setting in main.cf, e.g.

mynetworks = [::ffff:]/104 [::1]/128

Try sending an external email again, using telnet as before. You should be able to do so without any issues.

Now we want to see what kind of response someone would get if they were connecting from outside of the IP range defined in mynetworks, to make sure Pi won’t allow everyone to send outgoing emails from your server. To simulate this we can comment out permit_mynetworks under smtpd_recipient_restrictions:

smtpd_recipient_restrictions =
#       permit_mynetworks,

Now reload the postfix configuration:

sudo service postfix reload

This will let you see what kind of response you would get if you weren’t sending the email from mynetworks. Try sending again, and you should receive an error “554: Relay access denied“:

admin@samhobbs /etc/postfix $ telnet localhost 25
Connected to localhost.
Escape character is '^]'.
220 samhobbs.co.uk ESMTP Postfix (Debian/GNU)
ehlo samhobbs.co.uk
250-SIZE 10240000
250 DSN
mail from: USER
250 2.1.0 Ok
rcpt to: me@externalemail.com
554 5.7.1 <me@externalemail.com>: Relay access denied
221 2.0.0 Bye
Connection closed by foreign host.

Perfect. Leave permit_mynetworks commented out in your smtpd_recipient_restrictions (you'll see why in part 2).

Helo access restrictions

Helo access restrictions can be a very useful way of blocking spam.

Note that we’re not talking about unauthorised people being able to send email outside your network any more (that’s taken care of with the smtpd_recipient_restrictions); we’re now talking about stopping spammers from sending incoming mail to your email address.

Spammers try to conceal their identity so that they don’t end up on block lists, so they rarely use helo hostnames that could identify them – these hostnames are written to the mail log files. As a result, they often make up a random string or use an IP address instead of a domain name.

Luckily, these are easily taken care of.

Add the following to /etc/postfix/main.cf:

smtpd_helo_required = yes
smtpd_helo_restrictions =
  • Line 1 requires people and programs to identify themselves when they send email, using the helo or ehlo commands I mentioned earlier.
  • Line 2 starts the list of restrictions.
  • Line 3 accepts any old rubbish in the ehlo if it comes from an IP address defined in mynetworks. If the connection isn’t connecting from an IP address in mynetworks, then the helo hostname is checked against the rest of the list.
  • Line 4 accepts any helo hostname if the client is authenticated with SASL (I added this to the tutorial recently after troubleshooting problems some people had in the comments – it allows you to connect from any network and still send messages through your Pi. Mobiles will usually work without this because most providers pass mail through their own proxies, so your Pi receives a connection from the proxy – which has a valid hostname – and not from the mobile, which may be called something like “android-b627cfe2efea7e67″).
  • Line 5 rejects connection attempts when the HELO hostname syntax is invalid.
  • Line 6 rejects non-fully qualified domain names (for example, foobar instead of foobar.com). This will also block those random strings, e.g. “kjhrsbvks”.
  • Line 7 rejects the helo hostname if it that domain doesn’t have a valid DNS A or MX record. For example, someone spamming you could make up a domain like theflyingspaghettimonster.com. If that domain doesn’t actually exist and have the right records, then your server won’t accept it as a hostname, and the email will be rejected.

If the helo hostname gets past line 7 and hasn’t been denied, it is accepted. You’d be surprised how much spam these helo access restrictions will block on their own (looking through my log files, I can see numerous spam scripts that have attempted to ehlo with my IP address), but there’s an extra step we can add in here to help:

Blocking people claiming to be your domain name

Many spammers try to send email to you after helo’ing with your own domain name. Since postfix doesn’t check whether or not they’re lying about their helo hostname, this will usually work.

But, since we’ve put permit_mynetworks at the top of the list, anyone actually sending an email from your domain will be accepted already. Anyone using your hostname who isn’t in mynetworks is an imposter.

So, add one more line to the end of the restrictions list:

smtpd_helo_restrictions =
        check_helo_access hash:/etc/postfix/helo_access

That last line checks a file for custom rules you’ve built in. Create the file:

sudo nano /etc/postfix/helo_access

Add the following lines, edited for your domain:

samhobbs.co.uk          REJECT          Get lost - you're lying about who you are
mail.samhobbs.co.uk      REJECT          Get lost - you're lying about who you are

Now tell postfix to map the file, and restart postfix:

sudo postmap /etc/postfix/helo_access
sudo service postfix restart

Now anyone who tries to ehlo with one of the hostnames you defined in that file gets rejected, and sees the “get lost” message. Your legitimate servers won’t have that problem, because they will already have been accepted higher up the list.

Neat, right? I found that little nugget of wisdom at unixwiz.net.

Moving on…

We’re almost done with Postfix now, athough there are a few bits of configuration that we’ll want to do once we’ve set up SASL with Dovecot, which I’ve chosen to lump in with the Dovecot tutorial.

In Raspberry Pi Email Server Part 2: Dovecot, we’ll set up Dovecot to provide SASL authentication and IMAP capability.

Please leave a comment if you’re having trouble with anything in this tutorial, and I’ll try and help you out!



This is a great tutorial, and walked me right through setting up Postfix on my pi server. Thank you very much!


When I try the
sudo chown -R USER:USER /home/USER/Maildir
I get the message
chown: invalid user

Am I doing something wrong?


Really well done tutorial. One of the best I have seen.

Did not spot I was editing the comments section and their was the actual mail_location directive below

Hello Sam I have been following this tutorial series and I want to say thank you it is built very well. My question for you is why does my SMTP server only work when using the command line? If i make an email and send it with the command line I have no problems it goes to it's location and isn't marked as spam but if I try to use thunder bird the connection times out and the email can't send. Do you know any possible fixes for this? Also second question when I send email to Gmail it works as expected but if I try to send an email from Gmail it fails know anyway to fix that?? Thank you -Adam

Hi Sam,

How do I remove or delete a user and their mailbox completely?

I have a user account which I want to get rid of which is not needed anymore...



Hi Jo,

Use this command:

sudo userdel -r username

the -r option removes their entire home directory (which is where their Maildir is located).


Hi Sam, thank you for the great tutorial. I've followed it and was unable to send an email. I was able to send an email from my usual email however after trying to send an email at the very first stage I kept getting a queued status.
My ip address has now been blacklisted. Before I resolve this blacklist I need to find out why I was blacklisted in the first place. I think it may have been because my ip address from logging on did not resolve with the current website that is on the net hosted as a website. There are no email addresses on that site hosted externally but I think it could be that that the ip address (locally on the raspberry pi) is not sending because it's domain resolution is not matching what's listed on the external server.

Hi Sam, many thanks for your response and the great tutorial, I've been trying to get input on the rapsberry pi forum https://www.raspberrypi.org/forums/viewtopic.php?f=36&t=192881 looking in my mail log I get the below which no matter what email address I send it to I get the below.
Checking the MX Toolbox last time I checked said it was blacklisted but it's not so clear now. It says 'reported by mxtoolbox.com and gives a date reference of today' however last time I looked it said a week or two ago. So I'm not sure if it is truly blacklisted; however with the mail logs always saying this what could this mean?

Sep 16 20:37:15 raspberrypi postfix/smtp[6466]: 767E93F0A4: to=, relay=mx00.gmx.net[]:25, delay=2313, delays=2312/0.05/0.25/0, dsn=4.0.0, status=deferred (host mx00.gmx.net[] refused to talk$$o talk to me: 554-gmx.net (mxgmx015) Nemesis ESMTP Service not available 554-No SMTP service 554-IP address is black listed. 554 For explanation visit http://postmaster.gmx.com/en/error-messages?ip=

You appear to be using a relay, which isn't covered by this tutorial. Is that intentional?

It's not really fair to ask me questions about something significantly different to the contents of this tutorial without explaining what you have done differently, especially when it seems the problem is with the relay and not with the tutorial.


Hi Sam, thanks for your comment, it's not really fair for me to be asking you any questions really as it's very kind of you to do this tutorial in the first place, let alone actually corresponding with me now; so your responses are greatly appreciated and I apologise for abusing your kindness.
I followed the tutorial exactly twice. I reinstalled and completely reformatted my pi to make sure I didn't fluff up the installation/ made any further ammendments that I wasn't aware of. Short answer here (long below) -

/etc/postfix/main.cf - relayhost =

Sorry I'm not trying to relay, I had tried this earlier as I followed and no matter what the 1st stage of sending the email was only showing as queued. The above is currently how it is and I am not trying to relay at the moment nor am I trying to email. I have followed the tutorial exactly upteen times now but just can't get it to work.

Long Answer:
After following the tutorial exactly it was not working and I was concerned that as my website being hosted on another ip address (external professional hosting) then when trying to send an email reverse dns lookup was seeing that the email being sent from postfix's ip address was not matching the email where it was sent from; thus rendering it as spam (hopefully I've explained my logic here).

Thanks again for your input, please don't feel indebted to answer as you've already kindly provided this tutorial and the many queries you get must be quite frustrating for you.


No worries, I had assumed gmx was a relay but looking into it more it seems it was the final destination for the outgoing email - my bad.

This may just be a restriction on those recipient servers you have tried to send messages to. Can you try and send an email to me to see if it gets through?

Do you have a static or dynamic IP address? Sometimes the dynamic IP address ranges given out by ISPs are marked as residential/not expected to have legitimate mail servers operating there, so lots of servers will block the range to reduce spam. If you get a static IP address this is almost always not the case (if you don't have one but you can get one without paying a massive monthly fee, go for it because it makes a lot of things easier).

If you have a website hosted on a different server, then the best thing to do is set up your DNS like:

MX: yourdomain.com 10 mail.yourdomain.com.
A: yourdomain.com IP_of_website_host
A: mail.yourdomain.com IP_of_mail_server

And then if you create an SPF or PTR record, you can use mail.yourdomain.com


Hi Sam, no worries at all; thanks again for your input.

I just tried sending you an email, it's current status is queued; which is the same as I've tried to send to all of my email addresses, so I doubt it'll send.

Yes Sir, I am on a dynamic ip address and other people are saying this is what the problem is too. My plan was to try to see if I was capable to get it working on a dynamic ip address without spending any money as I'm looking at moving houses in the next few months and didn't want to get an annual contract for hosting the site, especially if I was unable to get it to work.

Thanks again for your kind input. DNS records have me pretty confused at the moment. I've watched a few tutorials on them and have read quite a few articles but I suppose the only way I'll learn is by messing around with them myself. Hopefully I don't get blacklisted in my learning experience.

Thanks again Sam, great tutorials. Be nice to see postfix adapt to ipv6 soon.

It would be interesting to see what you get if you telnet samhobbs.co.uk 25, you should see something like this:

sam@T440s:~$ telnet samhobbs.co.uk 25
Connected to samhobbs.co.uk.
Escape character is '^]'.
220 samhobbs.co.uk ESMTP Postfix (Ubuntu)
ehlo samhobbs.co.uk
250-SIZE 102400000
250 DSN
221 2.0.0 Bye
Connection closed by foreign host.

I'm wondering if your ISP is redirecting all traffic on port 25 instead of blocking it like some others do - I was expecting you to be able to send to me since I don't have any of the IP address based restrictions that some big mail servers have implemented.

Also, have you seen my DNS tutorial? If you have DNS questions after reading it, feel free to post a comment there.


Hi Sam,

Thanks for your follow-up. Yes I get exactly what you say I would when contacting your server. I'm not sure if it's putting all telnet through port 25 however I was able to login via telnet previously on a smtp connection and send an email from my usual email ( a web hosted domain account) however it's not letting me do than now which is concerning.

I also progressed to the sasl part of the tutorial and managed to get through ehlo'ing my account but also was unable to send the email as with the same error as on port 25 with an unencrypted connection.

Thanks again Sam.

Hi Martin,

Have you done the commandline tests? Checked with any other mail clients? Since I wrote this, development of Thunderbird has stopped, and some other people have had problems with it (especially on windows).

I don't have any images because I want people to understand how to maintain the server themselves, which means going through all the steps!


Sam, Great Tutorial and I am working fine.
When I added the recipient access restriction postfix hung. It was fine when I put everything on one line in main.cf with no commas but comma separating them onto different lines caused telnet to connect but postfix not to respond. There is a relay access restriction line higher up in main.cf or maybe its just my version of postfix. others might have this issue .. John


The comma needs to be the last thing on the line, with a tab at the start of the next line. If you add spaces or other characters at the end of the line after the comma then postfix thinks the next line is a separate configuration parameter and not part of the list.


Will you please be more specific with these commands

sudo chown -R USER:USER /home/USER/Maildir
sudo chmod -R 700 /home/USER/Maildir

I am not able to execute them. The first one gives me an error message no such user and the second says invalid directory


You need to "replace USER with the username you are doing this for, and repeat for all existing usernames", i.e. if your username is "pi" (for pi@yourdomain.com) then the commands are:

sudo chown -R pi:pi /home/pi/Maildir
sudo chmod -R 700 /home/pi/Maildir


Hello Sam,

I was able to run a fully working mail server on my raspberry following your great guide. I've just tried to put everything in a docker image and it seems to work. As you might know, using docker you can anytime start a new container that has everything installed and running, but everytime you start with no data in it. My question is if there is a reliable way to backup all the mail data (including users, passwords, and all the mails) from a container and then import everything in a new one.

Searching around I've found a procedure that in practice says to:
- backup relevant users lines from /etc/passwd
- same for /etc/shadow, /etc/group, /etc/gshadow
- do a .tar.gz file of the relevant /home/users folders.

And to restore just to append the lines of the /etc/ files and restore the /home/ files using the .tar file.

Is this procedure fine and reliable enough?

What do you think?

Best Regards,


Hi Luca,

I've not used Docker myself but my brother had to use it for work and it sounds really useful. I think your approach sounds sensible (presumably you are including all of the postfix, dovecot and spamassassin config from /etc/ as well). Not sure I can think of anything else you need since you can easily rebuild your spamassassin database from your restored emails. Have you tested it?


I did a test but the result is that now I see all the sent mails but not the received ones. Maybe I did something wrong, or it is just a permission issue.. I don't know. Instead of trying again I am thinking about a completely different approach. A better way to create a service with docker is to create at least two containers, one with the logic and the other one with the data. This can be done very easily by creating a container with postfix and dovecot and another one with mysql. In this case, in order to backup data I would just need to backup the volume of the mysql container.

I've seen that there are many different ways to archieve this. I will try to merge your configuration with others that use mysql, but maybe you already have a procedure or some suggestions. Do you think it is feasible to use your general postfix/dovecot configuration with mysql?

Thank you,

Best Regards.

Seems like a good approach but to be honest I think if you are going to do that you will have to make significant changes - if you want everything in a database then you'd be better off putting everything in there instead of mapping users to system accounts like I have done. This will have a lot of knock on effects to things like the dovecot authentication config.

If you want to look into it more I suggest you start by reading about virtual user setups for postfix, seems like a better place to start.


Thanks for taking the time to write this :)

When I try the ehlo command in telnet I don't get the line you show if your example;

Escape character is '^]'.
220 samhobbs.co.uk ESMTP Postfix (Debian/GNU) --<-- this is the line I do not receive.
ehlo samhobbs.co.uk

and nothing seems to take when I try the telnet bits?

Did I miss something?


Add new comment