ISPmail tutorial for Debian Wheezy

There is a newer issue of thie ISPmail guide available if you are using Debian Jessie!

Welcome back to another issue of the ISPmail tutorial. You are interested in learning all the basics about running your own mail server on a Debian server? Be my guest. All you need is a computer running Debian “Wheezy” and an internet connection. This tutorial explains step-by-step how to set up such a server and give you lots of background information in the process. Depending on your internet connection and server hardware you will be able to run a reliable mail service for thousands of domains and users. Soon you will be a proud operator of a mail server that can:

  • receive and store email for your users from other mail servers on the internet
  • let your users retrieve the email through IMAP and POP3 – even using SSL-encrypted connections
  • let your users define rules what to do with incoming email – e.g. distribute them to their mail folders or reply automatically. These rules are server-based and work automatically.
  • receive and forward (“relay”) email for your users using SMTP authentication
  • offer a beautiful webmail interface so that your users can manage their email just using a web browser
  • reject a lot of spam emails automatically
  • store your emails where secret services do not look

What this tutorial is *NOT* about

If you just need a no-cost mail server quickly and don’t care about the technical mumbo-jumbo then this is the wrong place for you. There are ready solutions like iRedMail if you are in a hurry. But running a mail server requires a minimal technical understanding. I personally recommend that you understand what you are doing. And that’s what the ISPmail guides are for. Experience from giving support in the #postfix channel on IRC shows that leisure sysadmins often fail because some detail in a complex setup goes wrong and they have no idea how to track it down. Go with ready solutions if you like. But I have a feeling that we meet again. And you will probably not save time either taking the easy route.

Does this guide work with other flavors of Linux?

Most of it does, yes. However certain paths in your file system may be different. And some software components like Dovecot may behave differently if you are not using the version that Debian Wheezy uses. So feel free to work through this guide to learn the basics. But be prepared if pieces do not work out of the box.


Maintaining such a complex tutorial is a lot of work. And I keep maintaining it in my spare time. So please respect the copyright. This document is copyrighted 2013 Christoph Haas ( Feel free to use it under the terms of the GNU General Public License. Don’t forget to refer to this URL and name me as an author when using parts of it. Feel free to contact me if you have any questions of leave a donation if you found the tutorial useful.

Things you will need

The server setup described here is totally standard work for a professional system administrator. Depending on your level of knowledge and experience you may walk through this document easily or need more patience to learn how to manage Linux systems. You will need to know about basic system administration tasks, DNS, SMTP, MySQL and POP3/IMAP. Make sure you have:

  • a computer to run Debian on (a cheap virtual server at your favorite ISP or a decommissioned desktop computer)
  • an installation medium if you don’t have a working Debian installation yet
  • an internet connection
  • basic knowledge on how to operate a Linux system
  • basic understanding of DNS, your own (sub-)domain and arbitrary control of the A and MX records of your domain
  • enough skills to install and configure a basic MySQL database server
  • control over the firewall that connects your server to the internet
  • a workstation running a mail client that speaks POP3, IMAP and SMTP (e.g. Mozilla Thunderbird, kmail or evolution)
  • a static IP address that is not a dial-up address because most internet providers will refuse emails from dynamic IP addresses – not sure? Go to and make sure that your IP address is not shown on any black-list.)
  • If your internet connection has a dynamic IP address then you will need an SMTP relay (most decent ISPs offer that) because you usually can’t send out emails directly to other mail servers.
  • 2 hours of time if you are a seasoned Linux administrator / 2 days if running your own Linux server on the internet is a new topic for you

About this tutorial

Many years ago I wanted to turn my Debian server into a mail server with virus scanning, spam detection, email forwarding, POP3 and IMAP access and a webmail service. All the components were available but it took a while until they worked properly together. So I summed up my desk full of scrawly notes into a tutorial that has become pretty famous. According to my web server statistics it’s still the most frequently read article at This document is not a simple copy-and-paste tutorial where you just copy the commands from the web site and run it on your server. Instead it will make you understand the different components that you are setting up. In the end you will be skilled enough to debug problems yourself. Unlike many other Postfix tutorials on the internet this is already the seventh edition. Writing this tutorial took a lot of work so these are not just quick draft notes thrown together but a consistent document guiding you. The whole tutorial is split into several chapters. Please use the links on the right side or below to navigate through the tutorial. If you prefer all content on a single page (e.g. for printing the tutorial) then use the “printer-friendly” link below. You are also invited to comment on the pages – just click on the “Add new comment” link at the bottom.

Changes from the previous “Squeeze” tutorial

  • Sieve filters are now much simpler to use. Dovecot 2.0 and Roundcube are an easy combination to let your users manage server-based email rules.

38 thoughts on “ISPmail tutorial for Debian Wheezy”

  1. Haha, I can’t believe this awesome timing. I’m currently setting up a new host to replace an old server. Looks like the tutorial has just come online a few days ago, so the timing couldn’t be better. Awesome work once again, thank you very much! 🙂

    1. Christoph Haas

      Heh, nice. And I've already taken way too much time as Wheezy has been released months ago…

  2. I’ve been waiting for this tutorial for a while, and it’s worth it. I just want to say thank you. Keep up the good work Christoph.

  3. HI, first, thanks a lot for this tutorial (I started with squeeze and through your guide I am self-hosting).
    Under the “Things you need”, it’s written a static IP or a dynamic IP with ISP relay. Does that mean that if I have a static IP, I can send directly mails to other mail servers, that I don’t need to relay through my provider anymore? (I’ve just changed to static IP provided by my ISP recently).

    1. Christoph Haas

      It depends. I enjoy saying that. 🙂

      The important part is whether the IP address is considered trustworthy or not. Search for "rbl check" on the internet and you will find services that help you determine wheter your IP address is listed in a blacklist. If you find it listed on a blacklist (and one that is not just experimental but commonly used) then you will have trouble sending email to other servers.

      The reason I'm emphasizing that dynamic IP addresses are bad is because dynamic addresses are more likely listed on common RBLs (blacklists). If you have bad luck then even a static IP address may be listed and it would be your turn to convince the operators of those blacklists to unlist your IP address.

      So if your IP is not shown on blacklists: feel free to send out email. 🙂

      1. DankeShun for your answer. I’ll try that soon.
        (RBL check didn’t complain about my IP).

  4. Hello,

    I would like to use sympa mailing list server on the same domain as the mailboxes. How will be my configuration with virtual transports and virtual_alias ?


  5. I will be reading though this whole document over the next couple of days/weeks. But I do have one question that may be advanced and would like to know if it’s covered or if not if someone could point me in the right direction.

    The “scenario” is that I have a ParentCompanyDomain and MyOldDomain. Most users have been migrated to the ParentCompanyDomain mail servers, others will never be migrated. So the setup needs to recognize based on the address from MyOldDomain whether to keep the mail in a local mailbox on this server, or to forward the email to ParentCompanyDomain. So for example if we receive mail to it should either keep it if he’s local, or forward it to

    Hope that makes sense and many thanks in advance for this tutorial and any help you provide!!!

  6. Steve Alderink

    Hi Chris….. Thank you for the “Internet’s greatest mail server tutorial”!
    I am a user for many iterations of Debian and run your setup on several of my servers for a “spam catcher” and a general mail server for everyday use.
    I have successfully been able to adapt to a couple different Distros including Fedora, Ubuntu and the latest is Slackware.

    My question is, would you be against me using the majority of the tutorial on another site?
    I am a huge fan of passing on what I have learned!
    The site I was thinking of is Howtoforge.

    If you are against such action I will honor your wishes.

    Thank you again!!

    1. Christoph Haas

      Steve, thanks for the kind feedback. It's nice to hear that you are a long-term fan of the tutorials. I myself will also soon set up yet another of those servers and it's still fun. 🙂

      Regarding Howtoforge… well… the operators of Howtoforge and I have a bit of an unfortunate relationship. Years ago they just copied one of the first versions of my tutorial, made hardly any changes, omitted my name, put their name under it and started to run ads on the site. So in the end they made money with my hard work. And as they did not reply to my complaints I informed their ISP who escalated the case. I don't mind Howtoforge as a provider of useful reading material. But I honestly don't see the reason to copy the tutorial (or larger parts of it) to another site.

      1. Steve Alderink


        No problem! I understand completely, that is why I asked.
        And yes, I sooo enjoy sitting down to create this as it gives me hours of time to spend with my PET Project.
        I will sometimes build on a new platform and then blow it all up and start on another platform.

        As an aside, I do NOT know what they have done with the postfix they put in Mageia, but you cannot run this setup chrooted.
        I have tried and failed 5 or 6 times now.

        Again, thank you for all you do, it is very much appreciated!

  7. Laïcana COULIBALY

    Thank you for tutorial. Everything work well for me. The mail server work well, I don’t have any problem at this point.
    My only problem is the connection between my outlook client with the mail server ? When i’m trying automatic connection, it doesn’t work. So I tried the manual configuration and same problem. What type of account do I have to choose on outlook ? IMAP or POP ? When I chose IMAP, I have to put the incoming and outgoing mail server so I put my server hostname (e.g: I insert also the email address and his password. Finally, in the username field of outlook I writed the email address too.
    This is what I got in the mail log:
    Apr 5 11:53:19 ns1 dovecot: imap-login: Login: user=, method=PLAIN, rip=, lip=, mpid=32703, secured, session=
    Apr 5 11:53:19 ns1 dovecot: imap( Disconnected: Logged out in=93 out=831
    Apr 5 11:53:37 ns1 postfix/smtpd[32704]: warning: hostname does not resolve to address Name or service not known
    Apr 5 11:53:37 ns1 postfix/smtpd[32704]: connect from unknown[]
    Apr 5 11:53:56 ns1 dovecot: imap-login: Disconnected (no auth attempts in 42 secs): user=<>, rip=, lip=, session=

    Outlook cannot connect to the mail server.
    Please help me.

  8. Jörg Zimmermann

    Mit Deinem HowTo hast du mir die letzten Jahre ne Menge Zeit gespart und dafür hab ich mich auch endlich mal revanchiert.
    Was mir noch fehlt ist eine wirklich zuverlässige Spam-Erkennung.

  9. Thanks for this great tutorial.

    I only comment for a minor misspelling: decomissioned should be decommissioned, with two m. 🙂

  10. Hi! First of all thank you for a great tutorial (the best from what I was able to find on web). I would like to setup my own mail server and initially planned to do this on Raspberry Pi (this will be home based server – must be so quite) but now not sure if it will handle everything considering it’s hardware specification. Do you have experience with running this setup on RPi? I’m aware that RPi is running Raspbian (based on Wheezy) and due to this fact some things may require different approach.

      1. Christoph Haas

        If you really use a Pi to run a mail server I'd be interested in your experience. I believe that its performance is enough but I'd like to hear first-hand.

        1. Pi, it’d work, but I’d be worried about wearing out the SD card.
          an external hard drive for /var could mitigate that.

  11. Could someone help me to install Mailman? I’m following some online tutorials but I don’t understand the ‘transport’ part.

  12. Thank you so much for your work ! I didn’t know anything about mail server and now I have a functional and “secured” domain for my company. It’s a great resource !

  13. Serigne Baytir DIENG

    Hi, I love this tutorial, thanks for doing such a good job. I have set up two MTA lets say (MTA1 which has as a virtual domain and MTA2 has as another virtual domain). MTA1 and MTA2 are not on the same subnet. How can I configure the two to send and receive emails from each other?

  14. Robert Chalmers

    I’m getting the following errors in the mail.log, and can’t figure it out. is a virtual domain, and fanney is the user name. All in the mysql database, and the postmap command finds it ok.

    postmap -q mysql:/etc/postfix/

    Where to ask about these problems?

    dovecot[22474]: lmtp(23033): Connect from local
    postfix/lmtp[23592]: 9FBA3883E88: to=,[private/dovecot-lmtp], delay=31, delays=31/0.01/0/0.01, dsn=5.1.1, status=bounced (host[private/dovecot-lmtp] said: 550 5.1.1 User doesn’t exist: (in reply to RCPT TO command))
    dovecot[22474]: lmtp(23033): Disconnect from local: Successful quit

  15. I am at the step preparing database, so far so good 😀

    Trying to migrate my complete web/mailserver from Windows Server 2008 to Debian 8.

    I have no experience in Linux-based OS whatsoever (ok, ls cd and old DOS stuff that is)
    The only thing which did not install was roundcube, package not found. So I installed Roundcube using some script on their website ( which I eventually was able to start.

    It stumbles upon something it wants from kolab thru git (which they don’t use anymore): Net_LDAP3,.
    But this is so far the only real error I had. I guess I can live without it.

    This manual is helping me a lot, even though I am not finished, it is great so far!

    Thanks for your time documenting this!

  16. Thank Very much,your document was so helpful,it helped me so much in mounting my mail server successfully and in short time.
    i have question: how to restrict using telnet connection to send message within my mail server without authentication,
    i noticed that every body could connect with telnet and send message to local mailboxes without authentication prompt
    how to force postfix to prompt for a login and a password to use telnet for sending emails

  17. I just installed the mailserver in compliance with this manual for Wheeze on my Debian Jessie server.
    I had only to do 2 extra thinks:
    in /etc/dovecot/conf.d/10-ssl.conf change

    ssl = no

    set to:

    ssl = yes

    and in /etc/dovecot/conf.d/15-lda.conf add an email address for postmaster_address (could not be empty)
    postmaster_address =

    Christoph, thanks for your traditional maiserver manuals. Great work!

  18. I have one issue now,

    In the mail..log I see all the mails sent to are sent to

    Oct 9 12:15:24 roubaix postfix/qmgr[12343]: 2F8BEE1F12: from=, size=1782, nrcpt=1 (queue active)
    Oct 9 12:15:24 roubaix postfix/trivial-rewrite[12360]: warning: do not list domain in BOTH mydestination and virtual_mailbox_domains
    Oct 9 12:15:24 roubaix postfix/trivial-rewrite[12360]: warning: do not list domain in BOTH mydestination and virtual_mailbox_domains
    Oct 9 12:15:24 roubaix postfix/local[12365]: 2F8BEE1F12: to=, orig_to=, relay=local, delay=0.17, delays=0.15/0.02/0/0, dsn=2.0.0, status=sent (delivered to mailbox)

    1. ok, remover my domainname from hostname and it seems working fine

      Thanks for your tutorial, it would be good if you add push for phones: )

      1. Glad you worked it out. Push for phones might be a problem. I’m not sure how iOS and Android handle that. IMAP offers an “IDLE” mode so that you get informed once an email gets in. But it requires a permanent TCP connection. That’s probably wearing the battery.

  19. Can you fix the “printer-friendly” link, because I can’t see it? Thanks. Good job with this tutorial!

    1. Christoph Haas

      I already tried to find a similar functionality. But I had to move the old broken (Drupal-based) web site to a WordPress installation. And so far I couldn’t find a plugin that allows me to provide such a link that concatenates all pages of the ISPmail guide. Perhaps a more experienced WordPress admin has a hint.

  20. Das Tutorial sieht genau nach dem aus, was ich gesucht habe – einen Mailserver zeitgemäß nach Best Practice aufzusetzen. Danke jetzt schon mal, Feedback dann sobald ich in den nächsten Tagen die Zeit finde, das Tutorial auch umzusetzen!

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to Top