ISPmail guide for Debian Stretch

christoph-haasThis guide will help you set up your own mail server while you learn how email transport and delivery works on the internet nowadays. I have maintained this guide since Debian Woody was released in 2002. Back then it took me weeks to get all the information I needed. Has that really been 16 years by now? Wow. Thank you all for your kind feedback and support – I would probably have discontinued this guide without you. And this is already the eigth edition.

See Marc Guillaume’s french translation if you prefer french.

Latest changes:

I am publishing this guide without any commercial interest. It just makes me happy to see more and more leisure sysadmins leave public freemail providers and operate their own servers. If you feel you would like to return the favor you can easily make me happy by clicking on the donation link at the bottom of this page. And please respect the copyright. I have seen literal copies of my work on the internet by people even making money with it. That’s annoying.

So what will the mail server cost you? The only recurring costs you may face are for running your mail server and for renting a domain. Cheap virtual servers are usually available at around $5 / 5€ per month and have enough power to run a mail server for your friends and family. The software being used is completely free and open-source. You can even make money with it. After all it is called “ISPmail” (ISP = internet service provider). Are you a sysadmin and your employer needs a mail server for their 500 employees? Go with this guide.

What your mail server can do

  • Receive emails on your domain(s).
  • Filter out spam and malware.
  • Send emails out to any other servers/domains on the internet. Connections will be encrypted when possible.
  • Add cryptographic signatures (DKIM) to outgoing emails.
  • Store as many emails for as many email addresses as you have disk space. Set limits (“quotas”) per user.
  • Let your users fetch email using IMAP or POP3 and send email through your servers using SMTP.
  • Allow users to manage server-based filter rules. Distribute incoming emails to different folders. Forward copies. Or send out-of-office notifications.
  • Provide a webmail interface so users can access their emails securely from any location.
  • Mitigate brute force attacks.

What you will need

  • Linux experience. Preferably a Debian-derivative. No godlike skills required. But know your basics: navigating through the file system, editing files, watching log files and having basic understanding of DNS and SQL (SELECT, INSERT, rows, columns).
  • Time. 2 hours to 2 days depending on your skills.
  • server that runs with Debian Stretch. 1 GB of RAM and a 20 GB disk is fine for your friends and family. Rent a cheap virtual server. Or use a decommissioned laptop. Other Linux distributions likely come with other versions of the software and have different default configuration – so your mileage may vary if you use anything else than Debian.
  • A public IP address that does not belong to a range of typical ISP customers. You usually can’t operate the mail server from a dialup IP address at home because those IP ranges are globally blacklisted. Make sure that your IP address is not blacklisted before you start.
  • An internet domain (or more) to receive emails for. You need to be able to set A, MX and TXT records for that domain.
  • Patience. We will proceed slowly and after every step ensure that you made no mistakes. Don’t hurry and skip parts even if they appear confusing at first. If you get lost just submit your question at the bottom of any page throughout this guide and help is on the way.

What this is not about

If you are lazy or in a hurry or just don’t want to learn about mail servers then this guide is not for you. There are ready solutions like iRedMail that you may want to consider. Running a mail server requires a certain technical understanding. And that’s what the ISPmail guide is for. Experience from giving support to other sysadmins shows that most problems appear because some detail in a complex setup goes wrong and they have no idea how to track it down. Email has evolved a lot over the past 40 years. 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. Or as one of the first long-haired nerds put it…

Everything should be made as simple as possible, but no simpler.
(Albert Einstein)


The whole tutorial is split into several pages. Please use the links on the right side to navigate through the pages. Make sure you have the server, a non-blacklisted IP and a domain ready. Let’s go.

41 thoughts on “ISPmail guide for Debian Stretch”

    1. Barco van Rhijn

      Thank you for how detailed and easy to understand you’ve made this guide. You’re Awesome!

    2. Barco van Rhijn

      Thank you for how detailed and easy to understand you’ve made this guide. You’re Awesome!

      I’m following along and applying this to Ubuntu 18.04.

  1. sanjibukai

    Yep big thanks for all those clear and clean explanations..
    In my case I will try to adapt this tutorial using docker containers instead..
    But since I’m a newbie, it will be hard..
    Any further lectures are welcome..

  2. Nice, good work. I’ll wait until you have completed the guide with the other sections and then setup a new server.

    love your work

  3. Ali Moreno

    Using your clean, well curated, and explained guides since Debian Sarge, first time I configured a mail server, thanks to you.

    I really want to thank you for all these years maintaining this valuable contribution. Not only useful but amazingly educative too!

  4. Lloyd Bacquers

    Hi, does this support soft quota? I can’t seem to find it anywhere in the guide.
    Love the docu though, i learned a lot.. I’m thinking of migrating from courier to dovecot, any thoughts?


    1. Christoph Haas

      It will. I have a few pages still in the making. The next two pages will be about virus scanning and DKIM signatures though.

  5. Thank you for your hard work.

    Kimsufi servers KS-1 just available, I think it’s time to migrate my old (wheezy…) mail server.

    Now I know what I will do this Week-End 😉


  6. Nice work!
    I think you could register a free domain instead of using
    This will be much clearer.

    Just my opinion!

  7. I used your guide with Ubuntu and it works like a charm. Many thanks for this extremly helpful and instructive guide. Finally I have my own mailserver. 🙂

  8. Are there any updates on the strech guide to be expected? As far as I remember there should also be at least a section in quotas. Any plans on when this will be published? Anyway thanks for your effort and especially for explaining the background stuff in an easy and understandable way…

    1. Try this:

      mysql> ALTER TABLE `virtual_users` ADD `quota_kb` INT NOT NULL

      Enabling quota plugins


      mail_plugins = $mail_plugins quota


      protocol imap {

      mail_plugins = $mail_plugins imap_quota


      uncomment sql:

      userdb {
      driver = sql
      args = /etc/dovecot/dovecot-sql.conf.ext

      comment static

      # userdb {
      # driver = static
      # args = uid=vmail gid=vmail home=/var/vmail/%d/%n
      # }

      Add user_query on /etc/dovecot/dovecot-sql.conf.ext

      user_query = SELECT CONCAT(‘/var/vmail/’,CONCAT(SUBSTRING_INDEX(email,’@’,-1),’/’,SUBSTRING_INDEX(email,’@’,1))) AS home, 5000 AS uid, 5000 AS gid, CONCAT(‘*:storage=’,quota_kb) AS quota_rule FROM virtual_users WHERE email=’%u’;

      It works for me 🙂
      And finally add quota plugin on roundcube.

  9. Petronel Malutan

    Hi ! Just jumped from Jessie here. I did installed a Debian 9 and run the playbook, without any apparent errors
    result : ok=72 changed=68 unreachable=0 failed=0

    The main issue i have and I would like to see how to fix it is Roundcube error:

    Also, does any of you have the tasks for adding any of the web management specified ?

    1. Petronel Malutan

      And yes 😉 Sorry I did not start with… Thank you ! Is the best article helped me to understand more about mail servers and ansible too 😉 BIG thank you 😉

  10. Hi,
    it’s long time i follow your ISP Mail guide for debian and it’s my reference any time i come across the postfix/dovecot/mysql/roundcube squad 🙂
    It’s also long time i look for a cms/framework, ‘isp like’ web application, allowing users to register to my mail system via web .
    It would be also nice if users once registered using their email addresses and passwords nad use the same credentials to login also to other services like jabber or vpn.
    I’m really greatfull for your work, i own my inbox 😉 !
    Hope it’s clear what i just wrote english is not my mother tongue 🙂

  11. hello,
    I have been following this tutorial for ages. Now I don’t have a webserver anymore but I still have the Maildir of my account.
    I’d like to be able to open some old mails from that folder in a GUI such as Thunderbird for example (I am on ubuntu). How can I so this ?
    I can open one email after another but I can’t seem to find a way to retrieve them as a list in my GUI. The file name of my email are as follow :,Sad

    Can you advise ?
    Thanks a lot

      1. Thanks for the short reply, no in Thunderbird it is not exactly functioning, you can open one email after other but you can’t see the full list of email as in a normal account
        I’ll try mutt.

  12. Pff, I don’t even know where to start with mutt. No really I’d prefer being able to see the message in a style like roudcube or other. Can I just install round-cube and postfix to view my emails ?

    1. Christoph Haas

      Mutt is powerful but not really intuitive. 🙂 “mutt -f Maildir” will open the folder. Then you press:

      T = select
      . = all
      ; = bulk-action
      b = bounce

      If you have at least a working Postfix (or other SMTP service like ssmtp) on that system you can bounce (=forward) the emails to another address.

      Or you try this advice to just use mutt to convert the Maildir to an “mbox” file that can be opened with Thunderbird.

      1. Sorry I had not seen your message.
        That last advise sounds good. How do I just use mutt to convert the Maildir to an “mbox” file ?

  13. Or would anyone using a mailserver such as the one described in this tutorial, give me a temporary account on his/her server, just so I pass him/her my archive (it’s 900MB) and I transfert them in POP in my gui ?
    Is there such a kind person here ?

    1. I am asking a last time not to pollute this useful site.
      I have an old Maildir (900MB) with my own personal emails from the last server I administrate.
      I absolutely need to review them but I do not have a server to put them on and navigate through a nice webmail interface.
      Could any administrator here with a mailserver such as the one described in this tutorial, be kind enough to create a temporary account for me to review my emails on a roundcube (for example) interface. I would only need to read them for a day make the backup I need and then the account could be closed. Or should I offer some money (I don’t have a lot).
      Hoping someone could help.

  14. Patrick Kloepfer

    Just followed the updated guide to move old jessie server to new stretch. I will tell you this is a complex process (building a mail server, not the move, you make that really easy) and without this guide it would be months to get something bad running, where as now I have a pretty robust system in days. The Guide is invaluable. Having now done it 3 or 4 times, I can tell you that when it doesnt work its my own dang fault. This build was no different and the 3 problems I had were all because I missed a step or had a typo and again the guide was excellent to point out what to check.

    One thing that many people (including myself) would like is a single doc to print to follow along and make notes, etc. I had a question for you, since this is all in WordPress, is all the writing done in standard MarkDown? If so we could copy each of the source pages markdown text and put it into an external MD editor and come of with a nice PDF.

    1. Christoph Haas

      Thanks for the nice words. Glad to see that the guide is still useful. Regarding the one-page document… I wished I had found a way to do that. It’s currently basic HTML written in the WordPress WYSIWYG editor. Before WordPress I used Drupal which had a print option that gathered all subpages into a single document. There is nothing ready for WordPress so it would be so cool to have a PHP-capable developer step up and create something for that. I’m totally not a PHP guy though.

  15. The GPL program Pandoc will convert fairly simple html into PDF, or markdown, or quite a few other things.

    1. Christoph Haas

      Thanks for the hint. However as a perfectionist I would prefer something that automatically tracks the linked documents, puts the TOC only at the front and then creates a new document on any change.

      1. I think Pelican does that, but not sure; certainly it converts blog posts into PDF. Blogdown/Bookdown might be more what you are looking for; it does sequential chapters well.

  16. Thank you Christopher so much for your excellent work over the years with this documentation.

    I have one question, can we somehow check and even quarantine outgoing email based on spamassassin checks? This would help keep the email server out of blacklists.

  17. There are instructions on setting Postfix to talk to Postgresql as contrasted to Mariadb/MySQL at

  18. Hi,
    I found a similar ISP Mail (Caramel Edition) that fashion very similar after Christoph’s ISPMail – But it is based on postgres instead of mysql, in addition it uses nextcloud for file transfer and accessing webmail.

  19. Any chance of a Z-Push addition for this version of the guide? I’ve been trying to get it going but keep running into errors.

Leave a Reply

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

Scroll to Top