Install Mail-in-a-Box

Mail-in-a-Box turns a fresh Ubuntu server into a self-hosted mail stack — Postfix, Dovecot, Roundcube, Let's Encrypt TLS, spam filtering, and DNS — managed through a single HTTPS admin panel. It is opinionated by design: it expects a dedicated VPS, a clean OS install, and full control over DNS. That trade-off buys you a production-grade mail server with one command and no manual config file editing.

Prerequisites and Server Requirements

Mail-in-a-Box is strict about its environment. Before running the installer, verify every point below.

• Ubuntu 22.04 LTS (64-bit), freshly installed. The project tests against this release only. Ubuntu 24.04 is not yet officially supported as of version 60.x.
• Dedicated VPS or bare-metal server. Do not install on a machine running other services — MiaB assumes exclusive ownership of Postfix, Nginx, and DNS.
• Minimum 1 GB RAM (2 GB recommended). Spam filtering via rspamd is memory-hungry.
• A fully qualified domain name (FQDN) set as the system hostname before install, e.g. box.yourdomain.com.
• Static public IP address. Dynamic IPs cause mail delivery failures and blacklisting.
• Ports 25, 465, 587, 993, 443, 80 open at the firewall/security-group level. Many cloud providers block port 25 by default — request it be opened before you start.
• Root or passwordless sudo access over SSH.

Step 1 — Set the System Hostname

The installer reads the system hostname to determine the box's primary domain. Set it before running the install script.

sudo hostnamectl set-hostname box.yourdomain.com

Confirm it took effect:

hostnamectl status

You should see Static hostname: box.yourdomain.com. Also verify /etc/hosts maps 127.0.0.1 and the public IP to the FQDN, or the installer will warn you.

Step 2 — Update the System

Start from a clean, fully updated state. The installer will refuse or produce unpredictable results on a partially updated base system.

sudo apt update && sudo apt full-upgrade -y
sudo reboot

Reconnect via SSH after the reboot before continuing.

Step 3 — Run the Installer

Mail-in-a-Box provides a single bootstrap command. Run it as your normal sudo-capable user, not as root — the script escalates internally.

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

The script will:

1. Prompt for the primary email address you want to create (e.g. [email protected]).
2. Derive the box hostname from the subdomain portion of that address if it differs from what you set.
3. Install and configure Postfix, Dovecot, Nginx, rspamd, Roundcube, Nextcloud (lightweight), and a built-in NSD nameserver.
4. Obtain a Let's Encrypt certificate for the box hostname automatically.

Installation takes 10–20 minutes depending on server speed and network. The terminal shows each component as it is configured. At the end it prints the admin panel URL and a temporary password.

Step 4 — Configure DNS

This is the most involved part, but MiaB does most of the work. Log in to the admin panel at https://box.yourdomain.com/admin and navigate to System → External DNS. You will see a table of every DNS record the box needs.

Option A: Let MiaB be your authoritative nameserver (recommended)

Point your domain's NS records at the box itself. At your domain registrar, set custom nameservers to ns1.box.yourdomain.com and ns2.box.yourdomain.com (both resolve to your box's IP — MiaB registers glue records automatically). Propagation takes up to 24 hours.

Option B: Use an external DNS provider

Copy every record from the External DNS page into your DNS provider's control panel. Critical records to get right:

• MX — points your domain's mail to box.yourdomain.com
• SPF (TXT) — authorizes the box's IP to send mail for your domain
• DKIM (TXT) — long public key under mail._domainkey.yourdomain.com
• DMARC (TXT) — policy record under _dmarc.yourdomain.com
• DANE/TLSA — optional but shown in the table; improves delivery trust

The admin panel marks each record green once it detects correct propagation. Do not proceed to sending mail until MX, SPF, and DKIM are green.

Step 5 — Explore the Admin Panel

The web UI at https://box.yourdomain.com/admin is the only interface you need for day-to-day management. Key sections:

• Mail → Users — add, remove, and set passwords for mailbox accounts and aliases.
• Mail → Aliases — create address aliases and catch-all forwarding rules.
• System → TLS Certificates — provision or renew Let's Encrypt certificates for hosted domains.
• System → Backup — configure encrypted backups to local storage or an S3-compatible bucket.
• System → Status Checks — a comprehensive checklist of DNS, TLS, and service health. Treat every red item as a blocker.

Step 6 — Send a Test Message and Verify

Log in to Roundcube at https://box.yourdomain.com/mail with your new address. Send a message to a Gmail or Outlook address and check that it arrives in the inbox (not spam). Then use the external tool below to confirm your mail authentication records are read correctly:

# Send a test message to the mail-tester scoring service
# Replace the random address shown on mail-tester.com
echo "Test" | mail -s "MiaB test" [email protected]

A well-configured box should score 9/10 or 10/10 on mail-tester.com. Common deductions are a missing PTR (reverse DNS) record and a missing DANE/TLSA record.

Step 7 — Set the PTR / Reverse DNS Record

This is set at your hosting provider, not in your DNS zone. Find the option labelled "Reverse DNS" or "PTR record" in your VPS control panel and set it to your box's FQDN (box.yourdomain.com). Without this, many receiving mail servers will reject or defer your outbound messages.

Verify propagation:

dig -x YOUR_SERVER_IP +short

Expected output: box.yourdomain.com. (will vary; reflects what your provider has set)

What Mail-in-a-Box Manages For You

Understanding the scope of automation helps you avoid breaking things by editing files directly.

• TLS certificates — automatically renewed via Let's Encrypt; do not install certificates manually.
• Firewall (ufw) — MiaB configures ufw rules during install. Adding your own rules is fine; do not disable ufw.
• System updates — unattended-upgrades is enabled for security patches. Full upgrades between Ubuntu releases require a fresh MiaB install; do not run do-release-upgrade on a running box.
• Spam filtering — rspamd handles inbound scoring and DKIM signing of outbound messages. Tune thresholds from the rspamd UI linked inside the admin panel.
• Backups — daily encrypted backups are written to /home/user-data/backup/ by default. Configure S3 offsite storage in System → Backup.

Troubleshooting

Status Checks page shows red items after DNS propagation

Re-run setup to refresh the internal state: sudo mailinabox. This is safe to run at any time and will not overwrite user data.

Mail lands in recipient spam folders

Check that PTR, DKIM, SPF, and DMARC are all green in the admin panel. Also verify your IP is not on a blocklist at MXToolbox Blacklists. New VPS IPs from some providers are pre-listed — request delisting before trying to send.

Let's Encrypt certificate fails to provision

Port 80 must be reachable from the public internet. Check your cloud provider's security group or firewall rules. The box's own ufw should already allow it, but an external firewall may block it.

Upgrading Mail-in-a-Box to a new release

Re-run the installer script or run sudo mailinabox. Check the changelog first for breaking changes before upgrading across major versions.