How to Set Up a Mail Server with Mail-in-a-Box

Mail-in-a-Box is an opinionated installer that turns a fresh Ubuntu server into a complete mail server: Postfix and Dovecot for SMTP and IMAP, Roundcube webmail, Nextcloud for contacts and calendars, its own DNS server, Let's Encrypt certificates, spam filtering, backups and a web control panel. In this tutorial you will prepare the server and DNS, run the installer, delegate your domain's DNS to the box, and verify everything with the built-in status checks.

Prerequisites

To follow this tutorial, you will need:

• A fresh server running the Ubuntu release that Mail-in-a-Box currently supports. At the time of writing that is Ubuntu 22.04 LTS (64-bit); check the official setup guide before you start, because the installer refuses to run on any other version. Do not install anything else on this server.
• At least 1 GB of RAM (512 MB is the hard minimum) and 10 GB of free disk space, plus room for mail.
• A non-root user with sudo privileges.
• A domain name, referred to as your_domain, where you can change nameservers and create glue records at the registrar.
• A static public IPv4 address, referred to as your_server_ip, with reverse DNS (PTR) set to box.your_domain. Set the PTR record from your provider's panel or ask support to do it.
• Inbound and outbound TCP port 25 allowed by your provider. Confirm with support if you are unsure.

This tutorial uses box.your_domain as the server hostname. The hostname must be a subdomain, not your_domain itself.

Step 1 - Setting the hostname

Mail-in-a-Box uses the system hostname as the default box name. Set it before installing:

sudo hostnamectl set-hostname box.your_domain

Check the result:

hostname -f

box.your_domain

If hostname -f prints something else, edit /etc/hosts so the line for 127.0.1.1 reads 127.0.1.1 box.your_domain box.

Step 2 - Creating glue records at the registrar

The recommended setup lets the box act as the authoritative DNS server for your domain, so it can publish and keep up to date every record it needs (MX, SPF, DKIM, DMARC, MTA-STS, TLSA, autoconfig). For that, your registrar needs glue records, which map the nameserver names to your IP address.

In your registrar's control panel, find the section called glue records, child nameservers or host names, and create:

Do not change the domain's nameservers yet. You will do that after installation, when the box is ready to answer DNS queries.

Note

If you prefer to keep your DNS at an external provider, skip the glue records. After installation, copy every record listed in the admin panel under System > External DNS into your provider instead. The box cannot update those records for you later.

Step 3 - Running the installer

Update the system first:

sudo apt update && sudo apt upgrade -y

Mail-in-a-Box is installed by a bootstrap script that clones the project's Git repository into ~/mailinabox and runs the setup from there. Download it and read it before running it:

curl -fsSL https://mailinabox.email/setup.sh -o mailinabox-setup.sh
less mailinabox-setup.sh

Run it:

sudo -E bash mailinabox-setup.sh

The installer asks a few questions in text dialogs:

1. Your email address: the first mailbox to create, for example admin@your_domain. This account becomes the administrator.
2. Hostname: confirm box.your_domain.
3. Time zone: pick your region.
4. Password: choose a strong password for the first mailbox.

Installation takes 10 to 30 minutes. It configures UFW, fail2ban, Nginx, Postfix, Dovecot, Roundcube, Nextcloud, the DNS server and certificates. When it finishes, it prints the admin panel URL and the fingerprint of the temporary self-signed certificate:

Your Mail-in-a-Box is running.

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

https://your_server_ip/admin

Step 4 - Delegating DNS and getting a real certificate

Now that the box answers DNS queries, point your domain at it. At the registrar, change the nameservers of your_domain to:

ns1.box.your_domain
ns2.box.your_domain

Delegation can take from minutes to a couple of days depending on the TLD. Check it from the server:

dig +short NS your_domain @8.8.8.8
dig +short MX your_domain @8.8.8.8

ns1.box.your_domain.
ns2.box.your_domain.
10 box.your_domain.

Once DNS resolves, log in to the admin panel at https://box.your_domain/admin (accept the self-signed certificate warning this one time) with the email and password from Step 3. Go to System > TLS (SSL) Certificates and click Provision to obtain Let's Encrypt certificates for the box and your domain. The box renews them automatically after that.

Step 5 - Passing the status checks

Open System > Status Checks. This page tests the firewall, services, DNS records, reverse DNS, certificates and blocklists, and explains how to fix each problem it finds. Aim for every item to be green before you rely on the server.

You can run the same checks from the command line:

sudo ~/mailinabox/management/status_checks.py

Common warnings on a new box:

• Reverse DNS is not set correctly: the PTR record for your_server_ip must be exactly box.your_domain.
• Nameserver glue records are incorrect: the glue records from Step 2 are missing or point to the wrong IP.
• The IP is listed in a blocklist: request delisting from the listed provider, or ask your hosting provider for a different address.

Step 6 - Adding users and aliases

In the admin panel, go to Mail & Users > Users to add mailboxes, and Mail & Users > Aliases to create forwarding addresses such as info@your_domain delivering to admin@your_domain. The same page lets you give a user administrator rights.

The admin panel is built on an HTTP API, which you can use for automation. For example, to add a user:

curl -X POST --user admin@your_domain:your_admin_password \
  -d "email=alice@your_domain" \
  -d "password=alice_strong_password" \
  https://box.your_domain/admin/mail/users/add

mail user added

Replace your_admin_password and alice_strong_password with real values. The full list of API calls is shown in the admin panel under Mail & Users > Instructions.

Step 7 - Using webmail, contacts and calendars

Each user has access to these services with their full email address and password:

• Webmail (Roundcube): https://box.your_domain/mail
• Contacts and calendars (Nextcloud): https://box.your_domain/cloud

Desktop and mobile clients configure themselves through the autoconfig records the box publishes. For manual setup, use:

On Android, DAVx5 syncs contacts and calendars with the CardDAV/CalDAV URL above. On iOS and macOS, the admin panel's Contacts/Calendar page links to a configuration profile. To confirm outgoing mail passes authentication, send a message from Roundcube to an external mailbox and check for spf=pass, dkim=pass and dmarc=pass in its headers.

Step 8 - Configuring backups

Mail-in-a-Box keeps an encrypted, incremental backup of all user data (mail, contacts, calendars, certificates and settings in /home/user-data) and runs it nightly. By default it is stored on the same server in /home/user-data/backup/encrypted, which does not survive losing the server.

In System > Backup Status, choose a remote target: an rsync server over SSH, an S3-compatible bucket, or Backblaze B2. Enter the credentials and save. The page then lists completed backups and their sizes.

The encryption key lives in /home/user-data/backup/secret_key.txt. Copy it somewhere safe off the server, because without it the backups cannot be restored:

sudo cat /home/user-data/backup/secret_key.txt

Step 9 - Updating Mail-in-a-Box

Updates are installed by running the bootstrap script again. It fetches the latest release, applies it and keeps your data and settings:

curl -fsSL https://mailinabox.email/setup.sh -o mailinabox-setup.sh
sudo -E bash mailinabox-setup.sh

The status checks page tells you when a new version is available. Ubuntu security updates are installed automatically through unattended upgrades, which the installer enables.

Troubleshooting

Mail from other servers does not arrive: confirm Postfix is listening and check the log for rejections:

sudo ss -tlpn | grep ':25 '
sudo tail -n 50 /var/log/mail.log

Outgoing mail is stuck: list the queue with sudo postqueue -p. Deferred messages include the reason, often a blocked port 25 or a receiver rejecting your IP.

Certificate provisioning fails: Let's Encrypt must be able to resolve box.your_domain and reach it on port 80. Wait until the NS and A records resolve publicly, then retry from System > TLS (SSL) Certificates.

The admin panel is unreachable after a reboot: run sudo ~/mailinabox/management/status_checks.py; it reports which services are down. Rerunning the setup script repairs most configuration drift.

Conclusion

You now have a self-hosted mail server on Mail-in-a-Box with authoritative DNS, valid certificates, webmail, contact and calendar sync, and encrypted backups. Keep the status checks green, copy the backup key off the server, and rerun the setup script when a new release appears. As next steps, add aliases for role addresses such as postmaster@ and abuse@, host a static website from /home/user-data/www, or add more domains by creating users under them.