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!



I'll try to connect to you from here.

I'm actually not at home at the moment, and I don't have shell access to my server, or I'd check to make sure you're not being blocked by my firewall/fail2ban - possible but unlikely unless you've been making loads of unsuccessful authentication attempts.


Thanks for caring Sam, I really appreciate it. Let me know if you´re in Iceland and I will buy you a beer/tea :-P

Strange. There has to be something unusual in either your LAN setup, your ISP's setup, or something you did triggered fail2ban.

I'd suggest having a rummage through your router's admin settings to see if there are any filtering rules there that allow outgoing connections on port 25 to your ISP's subnet only. It might also be worth trying to connect to other SMTP servers in other countries to see what happens.

Tea and beer both would go down nicely :)

No, but I´m sure I can emulate that somehow. My Pi is behaving weird right now (Read from socket failed: Connection reset by peer. I´m going to setup Raspbian again from scratch and run through your tut again :-)

Hello Sam,

Thank you very much for all your great info; I highly appreciate that you took the time to write this thorough tutorial out! I've got everything working all the way up to part 4 of the tutorial, that's where I'm up to.

My question is regarding this part of the tutorial however, specifically the storage path of emails. In your listed configuration, every user would have their Maildir in /home/USER which is defined by /etc/skel/ and that's fine. But what if we were to take it one step further and change the Maildir path from the RPi's SD card to some USB drive like /dev/sdX or /media/loldrivehere/? The reason being a relatively limited disk space on the SD card compared to, say, a 1TB HDD. Could it be done?

Looking forward to hearing your response and once again, thank you for your thorough tutorials!

-Mr. Cloud

Hello Mr Cloud (I'm singing that song from the Simpsons "Mr Plow" in my head!)

It might be possible to move just the Maildir to an external drive, but if you want to do that you could just move the whole of /home. Best to take the SD card out of the pi and do this from a linux workstation:

  1. Make a backup of your SD card just in case something goes wrong
  2. Copy /home from the SD card to your external drive
  3. Add an entry in /etc/fstab (on the SD card, not your laptop!) mounting the drive on /home at boot (use UUID to identify drive/partition)
  4. Remove /home from the SD card
  5. Re-insert SD card and external drive. Cross fingers and toes. Boot Pi.

Or you could just move the whole lot to an external drive, which has other benefits (speed, reliability):

Glad the tutorials have been useful!


Actually I just moved the home directories to the external media drive and created symlinks to them in /home.

Then a whole lot of services will store and retrieve from the external drive without needing any additional config. Some system users are staying on the sd card though so that they go wherever the card goes.

Thank you for the prompt reply, Sam. I decided to move the whole partition to external drive (HDD, 100gig+) following your link and everything is working as expected. The only thing I had to redo after doing this change was to sudo chown -R 777 /media/* because they were being mounted in /etc/fstab by root, so my pi account didn't have write access to them. But after that, so far so good!

Mr. Cloud

PS- Mr. Cloud, that's my name; that name again is Mr. Cloud! <3

Cool! I think you typed chown by mistake (you meant chmod?). If you wanted more secure permissions you could chown the drive to be owned by user pi - this persists after rebooting because the info is stored in the actual filesystem on the drive. Try:

chown -R pi:pi /media/drivename

...then you can set the permissions to whatever you like - at present, any user/process on the server could read those files.


Hi Sam,

First of all, thanks so much for your great tutorial - it's so well written and easy to understand even for a newbie like me.

I followed it step by step last night, and when I got to the testing part, it told me that everything went alright (even though I didn't receive any email at the tested recipient address, but that's another issue).

After that, I went to bed and this morning I wanted to continue looking into why I didn't receive the test mails. I logged in just as I did yesterday, started telnet and sent an ehlo command. I received the following error message:

221 2.7.0 Error: I can break rules, too. Goodbye.
Connection closed by foreign host.

I tried undoing all the changes to /etc/postfix/main.cf that I made during the tutorial, to no avail. Even a complete purge of postfix and dovecot off my system and clean reinstall didn't solve the problem. I keep getting kicked out right after the ehlo command.

Have you had this before or do you have any idea where I could have gone wrong?



Usually that error means e sent SMTP commands in the wrong order, or one of them was invalid. I suspect you made a typo, can you post the output from your telnet test please?

If it contains the authentication step, remember to redact your password before posting!



I'm almost too embarrassed to write back - I did use the wrong syntax. I had a colon (:) after the ehlo command. Everything works now, including receiving the test mail at the recipient address. Thanks so much again!


Thanks for letting us know, when people ask a question and then don't let me know what the solution was I'm always left wondering!

Enjoy having your own server, and thanks for commenting :)


Oh, I thank you for this awesome tutorial. I was actually wondering if you have a paypal account where I could send a virtual pint as a little token of my appreciation?

You're too kind! Thank you, really, but I get enough out of hearing how other people are getting on - no beer money necessary!

Instead, help out someone else on a Pi forum or something and complete the circle :)


Hi Sam.
Thanks for a super guide until now, but I have run into a problem.
I can not get telnet to work, I get this error no matter which port I tried:
root@raspberrypi:~# telnet localhost 25
Trying ::1...
telnet: Unable to connect to remote host: Address family not supported by protocol

It works fine out of the house, but not on localhost. I have searched through google, but can not find a solution. Can you help?

Please run this command:

cat /etc/hosts

Localhost should point to the loopback address like this:       localhost       samhobbs

# The following lines are desirable for IPv6 capable hosts
::1     ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

The "foreign host" thing makes me think localhost might not be resolving properly.


Thanks Sam. I may do some more experimenting but for now I did get things working with an SMTP provider. Oh, and a clarification on my first post. My ISP is CableOne and they use GMail for their email server. Sorry for the confusion :-).

Yes, it look more or less like yours

root@raspberrypi:~# cat /etc/hosts localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters raspberrypi


Do you get any errors when you restart postfix?

sudo service postfix restart


No errors.
[ ok ] Stopping Postfix Mail Transport Agent: postfix.
[ ok ] Starting Postfix Mail Transport Agent: postfix.

Yes, it's very weird

I wonder if postfix is only listening on IPV6 addresses and you're using IPV4 ( is IPV4).

Can you tell me what your inet_protocols parameter is set to please?

Also, try:

telnet 25

Just to check...


Same issue with

inet_interfaces = all
inet_protocols = ipv4
home_mailbox = Maildir/
mailbox_command =


Me again.
Telnet is now working, had to reinstall raspbian since I got stock.
But now a new problem has occurred. I'm not able to make "Testing SASL" working.
#Method No.1-2-3
echo -ne '\000testmail\000test1234' | openssl base64 are working fine, but when i'm trying to make it work with Telnet it doesn't show
AUTH PLAIN AHRlc3RtYWlsAHRlc3QxMjM0, it stops at 250 DSN.

Kind of like missing:

235 2.7.0 Authentication successful

Du you have any ideas how to solve it
Connected to localhost.
Escape character is '^]'.
220 brizarr.com ESMTP Postfix (Debian/GNU)
ehlo facebook.com
250-SIZE 10240000
250 DSN

When I do the rcpt to command, I get the following response:

554 5.7.1 : Relay access denied

Does anyone know what this is, why I'm getting it and how to solve it?



Add new comment