Fork me on GitHub
< Back to Mail-in-a-Box

Mail-in-a-Box Setup Guide

Pre-flight Checklist

Can I run my Mail-in-a-Box at home?
No. Computers on most residential networks are blocked from sending mail both on the sending end (e.g. your ISP blocking port 25) and on the receiving end (by blacklists) because residential computers are all too often hijacked to send spam. Your home IP address is also probably dynamic and lacks configurable “reverse DNS.” If any of these apply to you, you’ll need to use a virtual machine in the cloud.
What will it cost?
This is going to cost you about $12 per month. Most of the cost is in having a (virtual) machine connected to the Internet 24/7. You can divide this among friends and share your Mail-in-a-Box if you’d like to split it up.
Do I have time?
There’s also your time. Once a Mail-in-a-Box is set up, we hope it “just works” but when you are your own system administrator you must be prepared to resolve issues as they arise.
How will this affect my website? (Advanced.)
If your website is just HTML pages and static files, you can copy it onto your Mail-in-a-Box for a really simple hosting solution. If you have a website already, be aware that your Mail-in-a-Box wants to take over your DNS so that it can configure it correctly for email, and we recommend you let the box do that, but you can configure the DNS to keep your website on another machine. You may also need to configure relaying for outbound transactional email.

Can I modify my box after / use my box for something else too? (Advanced.)
No. Mail-in-a-Box must be installed on a fresh machine that will be dedicated to Mail-in-a-Box, and you cannot modify the box after installation (configuration changes will get overwritten by the box’s self-management). If you are looking for something more advanced, try iRedMail, Sovereign, or Modoboa.

Video Guide

There is a video version of this tutorial on the homepage.

Your Domain Name

The first step in setting up a Mail-in-a-Box is to pick your new email address. An email address has two parts. The part after the @-sign is the domain name. Each domain name is owned by someone, and you are going to be the owner of your own.

Josh’s email address is @occams.info. His domain name is occams.info.

Some domain names have quirks, depending on which “top-level domain” (TLD) it is under. Please consult this list:

  • Known good TLDs:
  • .com
  • .email
  • .fund
  • .guide
  • .info
  • .io
  • .me
  • .net
  • .uk
  • .me.uk
  • .us
  • Probably good TLDs:
  • .computer
  • .cz
  • .eu
  • .im
  • .name
  • .network
  • .nz
  • Avoid these:
  • .at
  • .ca
  • .de
  • .gg .je .as
  • .cx
  • .is
  • .nl
  • .bid .buzz .click .cyou .date .faith .fit .fun .gdn .icu .life .online .ooo .pro .review .site .space .stream .top .trade .vip .work .world .xyz
  • indicates link to discussion. indicates link to TLD registry requirements.

Next you will register your new domain name. It’s about $17/year, depending on the TLD. Buy basically anything you want, taking into account the TLD recommendations above. This will be the start of your new identity.

I recommend you use Gandi.net to register your domain name because I know it works well for Mail-in-a-Box. You can use other domain name registrars besides Gandi, but support for DNSSEC is not good everywhere. (DNSSEC is an optional security feature on Mail-in-a-Box. It’s nice to have but things will work just fine without it.)

Not all TLDs support DNSSEC either. If you will use Gandi, you should check their list of TLDs that support DNSSEC. For a more complete list of TLDs and their DNSSEC support, see ICANN Research TLD DNSSEC Report.

After you buy the domain name you’ll need to set it up, but that comes later so keep reading. Note that a Mail-in-a-Box box can handle the email for multiple domain names too — more on that later.

Your Box Has A Name

Every machine connected to the Internet has a name and an address.

The address, an IP address, is like a telephone number. It’s made up of numbers and is assigned to you by whoever provides Internet access to your mail server (that’s coming in the next section).

The name — called a hostname — is something you decide. It can be a domain name you own or any “subdomain” of a domain you own.

For your Mail-in-a-Box, we recommend naming your box box + . + your domain name.

Josh’s Mail-in-a-Box is named box.occams.info. This is its hostname.

Your Mail-in-a-Box may handle the email for multiple domain names, but the box has a single name.

Your box’s name CANNOT be a domain name that you intend to serve a website on from another web hosting service. We strongly suggest using a subdomain like box, as in the example above, so that you are able to use the main domain name for a website hosted from another web hosting service if you choose.

The Machine

Finding a cloud service provider

Now you will rent a machine, or a virtual part of a machine, somewhere in “the cloud.” We’ll call this machine your box. We recommend going over to Linode, 1&1, or Rimuhosting.com. (Most cloud providers will do, but not Amazon Web Services because its network is often blocked to prevent users from sending spam.)

You must choose the Ubuntu 22.04 x64 (server edition) operating system and a machine with at least 512 MB of RAM. This setup currently costs around $5/month, depending on which provider you choose. We recommend you to use a box with 1 GB of RAM which costs around $10/month.

If you choose Digital Ocean, your machine is called a “droplet” and you must name your droplet the same as its hostname.

Josh’s droplet would be named box.occams.info (if Josh used Digital Ocean).

If you have a choice, choose a location for your machine that is near you — it’ll be faster! And if disabling IPv6 is an option, disable it.

Reverse DNS

Each cloud provider will have different instructions for setting up “reverse DNS.” You must follow your cloud provider’s instructions for setting the reverse DNS of your box to your box’s hostname.

If you are using Digital Ocean, your reverse DNS is already done. (They automatically set it to what you entered as your droplet’s name, which per the instructions above was your box’s hostname.) Linode’s instructions are here, but you may not be able to set the reverse DNS on Linode until after you have finished the rest of this guide (Linode only accepts reverse DNS changes once the forward DNS is working, which your box will handle by the end of this guide). 1&1’s instructions are here.

Josh’s box’s reverse DNS is set to the same as the box’s hostname: box.occams.info.

Locate the machine’s IP address

Your cloud provider will also now tell you the IP address of your machine. It looks like 123.123.123.123.

Josh’s box’s IP address is 94.76.202.152.

Sometimes you might be assigned an IP address that is on a spam block list. You may wish to use a tool such as MXToolbox to ensure your IP address is not on these block lists. If you find your assigned IP is on a blacklist, you might have luck requesting a "clean" IP from your provider, or creating a new host if you're using a VPS service.

Firewall settings

If your machine is behind a hardware firewall (or virtual equivalent, such as an AWS security group), ensure that the following ports are open: 22 (SSH), 25 (SMTP), 53 (DNS; must be open for both tcp & udp), 80 (HTTP), 443 (HTTPS), 465 (SMTP submission), 993 (IMAP), 995 (POP) and 4190 (Sieve). It doesn’t hurt to block other ports, but your box will take care of that itself by configuring a software firewall on the machine itself.

Domain Name Configuration — Glue Records

We’ll now go back to your domain name registrar to associate your domain name with your box’s IP address. This has two parts: glue records and nameservers.

Glue Records

The association between your domain name and IP address is . . . complicated. The domain name system (DNS) is a global, distributed network of machines that turn domain names into IP addresses. Your registrar and your box play a role in the domain name system.

The way this works varies from registrar to registrar, but it goes something like this:

First, you’ll create two “glue records.” The purpose of glue records is to say that your box is becoming a part of the domain name system. These records go by different names at different registrars, so also look out for “hostnames” or “child nameservers.”. This will not be found in a DNS control panel. [Gandi instructions | GoDaddy instructions]

A glue record consists of a hostname and an IP address. You will need two: ns1. + your box’s hostname and ns2. + your box’s hostname. (They stand for “nameserver one” and “nameserver two”.) For the IP address, enter the IP address of your box.

Josh’s box’s hostname is box.occams.info. The two glue records are for ns1.box.occams.info and ns2.box.occams.info and list the box’s IP address of 94.76.202.152.

It looks something like what’s shown here:

Your registrar may ask you to enter these hostnames with the domain name part omitted, as mine did in this case. If so, enter the part of the hostname up to the domain name.

Josh’s domain name is occams.info. The two glue hostnames are ns1.box.occams.info and ns2.box.occams.info, but his registrar asks him to enter them with “.occams.info” omitted leaving just ns1.box and ns2.box.

If your Mail-in-a-Box is handling mail for multiple domains, you only do glue records once (for your first domain name). Additional domain names skip this step.

Some domain name TLDs and some registrars will require that you enter two glue records with different IP addresses. That won’t work for Mail-in-a-Box’s typical setup since your machine will only have one IP address. You can either set up secondary DNS servers to get around this limitation (it’s not hard, but it’s more work), or use a different domain name under a different TLD or a different registrar.

If you are using Namecheap, check out this comment on how to enter the information in their control panel.

Domain Name Configuration — Nameservers

Nameservers

Now you’ll tell your domain registrar that your domain name’s nameservers are ns1. + your box’s hostname and ns2. + your box’s hostname.

You will usually be turning off the registrar’s provided nameservers and turning on custom servers. This is usually not found in the domain name’s DNS control panel. You will be disabling that control panel.

Here’s what that looks like in my registrar:

Don’t worry if you are confused about what this all means. It is complicated — we all get confused at this point.

If you add another domain name to your box later, this section is repeated for each domain name you associate with your box. All domain names on the box will use the exact same two nameservers. So if you used ns1.yourdomain.com for your first domain, use exactly the same thing for your second domain name. (You do NOT use ns1.yourseconddomain.com, etc.)

DNSSEC DS Record

DNSSEC adds a security layer on top of DNS, in the same way that HTTPS adds a security layer to HTTP. It is not necessary, but it is recommended. When enabled, mail between Mail-in-a-Boxes will always be encrypted.

Your box’s control panel will tell you to come back to your domain name registrar at the end to configure the DNSSEC DS record. It’s not something the box can set up on its own, but you also can’t configure it until after the box itself is set up — so you will come back to this.

Setting Up The Box

You will now have to log into your running box using SSH. Your cloud provider will probably give you some instructions on how to do that. If your personal computer has a command line, you'll be doing something like this:

ssh -i yourkey.pem ubuntu@10.20.30.40
Legal note! Mail-in-a-Box is made available per the CC0 public domain dedication. By running Mail-in-a-Box, you will invoke scripts that use Let’s Encrypt to provision TLS certificates per the Let’s Encrypt Subscriber Agreement(s) & Terms of Services. Please be sure you accept the terms in both documents before proceeding.

Once inside, you will now get the Mail-in-a-Box code onto your box and start its setup. Copy and paste this into your terminal and hit enter:

curl -s https://mailinabox.email/setup.sh | sudo -E bash

You will be asked to enter the email address you want and a few other configuration questions. At the end you will be asked for a password for your email address.

This password will be used to login to webmail, the administrative interface, and on your devices. It will not be used to log onto your Mail-in-a-Box server using SSH (that’s what you did above).

It is always safe to re-run the setup, either because something went wrong or you just want to see it again. You can do so by following two the steps above again or just running sudo mailinabox from the command line.

When it comes time to update to a newer release of Mail-in-a-Box, you’ll literally just run the above two commands again (ssh ... and then curl ..., as above) on your existing machine.

The Administrative Interface

Connecting for the First Time

When the setup script is done running, you’ll been given instructions on how to access your box’s web-based administrative control panel:

Your Mail-in-a-Box is running.

Please log in to the control panel for further instructions at:

    https://94.76.202.152/admin

You will be alerted that the website has an invalid certificate. Check that
the certificate fingerprint matches:

C0:9B:FF:04:2B:2D:8F:47:5A:8B:D5:88:B7:05:D3:4B:6C:22:80:5F

Your SSL certificate is not yet signed so you will get a security warning when you visit the administrative URL. There is a way to proceed securely if you use Mozilla Firefox.

  1. Open the URL in Firefox. Firefox will say This Connection is Untrusted.
  2. Click on I Understand the Risks.
  3. Click on Add Exception.
  4. Click on View.
  5. Compare the SHA1 Fingerprint in Firefox to the fingerpint reported by Mail-in-a-Box’s setup script in your SSH connection (see the example above). If they match, it is safe to continue.
  6. Click on Close.
  7. Click on Confirm Security Exception. It is safe (and convenient!) to permanently store the exception.

The page will then load securely.

You can also get a signed SSL certificate later (see below) so you don’t have to go through these steps.

System status & DNS

Log in to the administrative control panel with the email address and password that you provided during Mail-in-a-Box’s setup. Proceed to the System Status Checks.

These checks will guide you toward finishing your setup:

The control panel will check if your DNS is set up correctly. Things related to the domain name system sometimes take several minutes, or much longer, to update. This is called DNS propagation. Wait for the control panel to report no DNS problems — reload the page every 15 minutes or so. If problems persist, something went wrong.

DNSSEC is an optional step that adds additional security to DNS. The control panel will walk you through setting up DNSSEC as well. You will need to go back to your domain name registrar and enter additional information.

If you skipped the DNS settings earlier, you should now go to the DNS (Custom/External) > External DNS section of the control panel and copy the DNS records into your own DNS control panel.

Getting a signed TLS (SSL) certificate

Use the TLS Certificates page of the control panel to provision a free TLS (SSL) certificate from Let’s Encrypt. If you don't want to use Let's Encrypt, you can also add any other certificate and import it in the box. The box will help you by generating a private key. Just follow the instructions given in the control panel.

Checking your email

The administrative control panel will provide instructions for how to check your email with webmail, IMAP/SMTP, or Exchange/ActiveSync.

You can also add or remove additional email accounts and mail aliases (forwarders).

Backup status

Here you can configure backups, and get an overview of what has been backed up to date. Backups are encrypted, and are therefore safe to store anywhere you like.

By default, backups are stored on the box. You can also configure rsync to copy those local backups to another server, or store backups entirely on Amazon S3, or another compatible service (e.g. DigitalOcean Spaces). With S3, no backups are stored locally, preserving some disk space on the box.

However you store your backups, you must copy the encryption password file described on the Backup Status screen somewhere safe! Backups cannot be decrypted without the backup key!

Advanced tools

The administrative control panel also helps you with...

  • Setting up contact and calendar synchronization
  • Publishing a static website
  • Setting custom DNS records, e.g. if you run a website on the same domain name but on another machine

Keeping Your Box Humming

Follow @Mailinabox on Twitter so you know when we post any updates to Mail-in-a-Box.

Check your box’s control panel periodically to see that the System Status Checks report everything is OK. Your box will also automatically email you whenever anything changes in the status checks.

Remember that it is always safe to re-run the setup script by typing sudo mailinabox at the SSH terminal prompt.

Finally, consult the Maintenance Guide for further questions.

Systems Checks

If you want to double-check that your system is configured correctly, here are some tools: