This guide covers how to install mailpopbox, set up auto-renewing TLS certificates, and setting up Gmail to POP messages off the server.
Mailpopbox can be deployed on a variety of operating system environments, but this guide is for a Linux server with:
- Root access and the ability to run long-lived processes (i.e. not shared hosting)
- The iptables package
I recommend Digital Ocean droplets, which cost $5/month. This guide does not cover how to properly secure a Linux server, such as SSH configuration and firewalls; please use other guides to do that if this is a new server instance.
These commands assume you are running as root; if not, precede the commands with sudo
.
-
Download the latest mailpopbox release and copy the binary to
/usr/local/bin
-
Set ownership and permissions:
chown root:wheel /usr/local/bin/mailpopbox
chmod 755 /usr/local/bin/mailpopbox
-
Create a new user that the server will run under:
useradd mailpopbox --shell /sbin/nologin
-
Create some directories with the correct permissions:
cd /home/mailpopbox
mkdir -p maildrop/yourdomain.com cert www/.well-known/acme-challenge
chown -R mailpopbox:mailpopbox maildrop cert www
-
Create a file at
/home/mailpopbox/config.json
:{ "SMTPPort": 9025, "POP3Port": 9995, "Hostname": "mx.yourdomain.com", "Servers": [ { "Domain": "yourdomain.com", "MailboxPassword": "yourpassword", "TLSKeyPath": "/home/mailpopbox/cert/certificates/mx.yourdomain.com.key", "TLSCertPath": "/home/mailpopbox/cert/certificates/mx.yourdomain.com.crt", "MaildropPath": "/home/mailpopbox/maildrop/yourdomain.com" } ] }
- The SMTP and POP3 ports are not the values that will be exposed to the Internet, as those are reserved ports that require root access to bind. Instead, mailpopbox binds these unprivileged ports and iptables will be used to route Internet traffic to the server. This is handled by the included systemd unit.
- The
Hostname
is the MX server hostname. Multiple catch-all domains can be configured on a single server, but they will all share this MX hostname in e.g. the SMTP HELO. - The
Domain
is the domain name for which*@yourdomain.com
will be set up. - The
MailboxPassword
is the password for themailbox@yourdomain.com
account, used to authenticate POP3 and outbound SMTP connections. Choose a strong (preferably random) password! - The
TLSKeyPath
andTLSCertPath
are used to find the TLS certificate, which will be configured below. - The
MaildropPath
is where delivered messages are stored until they are POP'd off the server.
-
Add a DNS A record to
yourdomain.com
, configuring the subdomainmx.yourdomain.com
to point to the public IP address of the server running mailpopbox. -
Set or change the DNS MX record of
yourdomain.com
to point tomx.yourdomain.com
.
Changes to DNS can take up between 1 and 24 hours to propagate. The DNS entries need to be configured in order to continue installation.
This guide will assume that your instance of mailpopbox is running on a system that also has a web server running. The web server will be used to host ACME certificate challenges. I recommend the lego tool for certificate management.
If you already have a mechanism to get certificates, you can use that and just adjust the paths in
config.json
. Also be sure to configure a hook for your auto-renew mechanism to restart mailpopbox when a new certificate is installed.
-
Install lego on the server.
-
Configure your web server to serve the content under the mailpopbox home directory. With an apache2 configuration, this can be done by editing
/etc/httpd/conf.d/mx.yourdomain.com
with this content:<VirtualHost *:80> ServerName mx.yourdomain.com ErrorLog logs/yourdomain_error_log CustomLog logs/yourdomain_access_log combined DocumentRoot /home/mailpopbox/www </VirtualHost> <Directory /home/mailpopbox/www> Require all granted </Directory>
You may also need to adjust the permissions so the web server can serve the files:
chmod o+x /home/mailpopbox
chmod o+rx /home/mailpopbox/www
-
Reload the web server
systemctl reload httpd.service
-
Customize this command and register for the initial account and certificate:
sudo -u mailpopbox /usr/local/bin/lego --email email@domain.com --domains mx.yourdomain.com --http --http.webroot /home/mailpopbox/www --path /home/mailpopbox/cert run
This will register email@domain.com with LetsEncrypt to get a
certificate for mx.yourdomain.com by putting an authentication challenge file in the
/home/mailpopbox/www
directory, with the resulting certificate files in /home/mailpopbox/cert
.
-
Let mailpopbox restart itself via systemd by editing the sudoers file with
visudo
, and add this line:mailpopbox ALL=(root) NOPASSWD: /usr/bin/systemctl restart mailpopbox.service
-
Set up a cron job to automatically renew the certificate using
sudo crontab -u mailpopbox -e
and specifying this command (which is nearly the same as therun
above, except it usesrenew
and a hook). Customize this command:0 22 * * * /usr/local/bin/lego --email email@domain.com --domains mx.yourdomain.com --http --http.webroot /home/mailpopbox/www --path /home/mailpopbox/cert renew --renew-hook "sudo /usr/bin/systemctl restart mailpopbox.service"
- Copy the
mailpopbox.service
systemd unit file from the release archive to/usr/local/lib/systemd/system
Note that the systemd unit file uses
/sbin/iptables
to forward traffic from ports 25 and 995 to the ports specified in theconfig.json
file. It also specifies the path to theconfig.json
file.
-
Enable the systemd unit with
sudo systemctl enable mailpopbox.service
-
Start mailpopbox with
sudo systemctl start mailpopbox.service
-
Verify that the server has started with
sudo journalctl -u mailpopbox
-
Test the connection to the server from your local machine:
openssl s_client -connect mx.yourdomain.com:995
. You should see your certificate printed byopenssl
and then a line that says+OK POP3 (mailpopbox) server mx.yourdomain.com
.
Now that mailpopbox is running and DNS is configured, it is time to set your mail client up to connect to it. We will set up both a POP3 account to download delivered mail, and a SMTP account to enable replying. This guide is for Gmail, but the configuration parameters are the same regardless of client.
-
Go to Gmail Settings > Accounts and Import
-
Under Check mail from other accounts:, click Add a mail account
-
Specify
mailbox@yourdomain.com
as the email address and click Next -
Choose Import emails from my other account (POP3) and click Next
-
Specify the following configuration and add the account:
- Username:
mailbox@yourdomain.com
- Password: The password you specified in
config.json
- POP Server:
mx.yourdomain.com
- Port:
995
- Check Always use a secure connection (SSL) when retrieving mail
- Optionally, apply a label to all the messages sent to this domain
- Username:
Gmail will now fetch messages delivered to the server. You can send a test message to
install-test@yourdomain.com
and it should be delivered within a few minutes. Note that Gmail
detects when a newly delivered message is the same as one in the Sent folder and it discards it;
use a separate email account for this test. Gmail also fetches mail from the POP account
periodically via polling, so message delivery can seem slower than normal.
-
Go to Gmail Settings > Accounts and Import
-
Under Send mail as:, click Add another email address
-
Specify the following and click Next:
- Name: Whatever you prefer
- Email:
mailbox@yourdomain.com
- Check Treat as an alias
-
Specify the following and add the account:
- SMTP Server:
mx.yourdomain.com
- Port:
25
- Username:
mailbox@yourdomain.com
- Password: The password you specified in
config.json
- Check Secured connection using TLS
- SMTP Server:
Gmail will now let you send email as mailbox@yourdomain.com
. But if you are replying to a message
sent to random@yourdomain.com
, you do not want the recipient to see the "mailbox" username in your
reply. If you append [sendas:random]
to the Subject line of the message, the SMTP server will
change the From address to random@yourdomain.com
and remove the special tag from the Subject line.