Mail-in-a-Box

Once installed, Mail-in-a-Box provides two primary ways to manage the server's configuration:

1. Control Panel: A web-based interface used for common administrative tasks such as:

   • Adding or removing mail users.
   • Managing email aliases.
   • Adding custom DNS records.
   • Configuring backup settings.

2. API: A programmatic interface that exposes all the same actions available in the control panel, allowing for automation and integration with other tools.

Mail-in-a-Box is designed to turn a fresh, 64-bit Ubuntu 22.04 LTS machine into a fully functional mail server. It is an appliance-style installation with no user-configurable setup options during the initial deployment.

Prerequisites:

• A completely fresh Ubuntu 22.04 LTS 64-bit machine.
• Access to the command line with sudo privileges.

Installation Steps:

1. Clone the repository.
2. Checkout the latest release tag.
3. Run the setup script.

For a more user-friendly, detailed guide, visit the official setup guide.

# 1. Clone the repository
git clone https://github.com/mail-in-a-box/mailinabox

# 2. Enter the directory and checkout the latest release tag
cd mailinabox
git checkout TAGNAME

# 3. Begin the installation
sudo setup/start.sh

The setup/start.sh script is the primary entry point for installing and configuring a Mail-in-a-Box system. It performs preflight checks (OS version, memory, /tmp mount options), sets up the environment (UTF-8 locales, ncurses fixes), handles system migrations, and configures core services including DNS, SSL, Postfix, Dovecot, and the web control panel.

When running for the first time, it will prompt for PRIMARY_HOSTNAME, PUBLIC_IP, and PUBLIC_IPV6. On subsequent runs, it reads existing settings from /etc/mailinabox.conf and runs migrations via setup/migrate.py.

# Recommended installation method (curl-pipe-to-bash)
curl -s https://mailinabox.email/setup.sh | sudo bash

The management/cli.py script is a command-line interface for calling management APIs on the Mail-in-a-Box control panel backend.

Requirements:

• The script must be run as root because it reads the root API key from /var/lib/mailinabox/api.key.
• It communicates with the management daemon listening on http://127.0.0.1:10222.

Important Note on User Removal: Removing a mail user via the CLI does not delete their mail folders on disk; it only prevents IMAP/SMTP login.

# Run as root
sudo python3 management/cli.py user

Global configuration options are stored in /etc/mailinabox.conf. This file is used by standalone tools to locate data and determine system settings. Key configuration variables include:

• STORAGE_USER: The user owning the mail data.
• STORAGE_ROOT: The directory containing all mail and configuration data.
• PRIMARY_HOSTNAME: The main hostname of the server.
• PUBLIC_IP: The IPv4 address of the server.
• PUBLIC_IPV6: The IPv6 address of the server.
• PRIVATE_IP: The internal/private IPv4 address.
• PRIVATE_IPV6: The internal/private IPv6 address.
• MTA_STS_MODE: The MTA-STS enforcement mode (defaults to enforce unless otherwise specified).

If your PRIMARY_HOSTNAME is not yet resolving correctly via DNS, you may see certificate warnings when accessing the control panel. You can verify the authenticity of the certificate by comparing the browser's fingerprint with the one generated from the local certificate file using:

openssl x509 -in "$STORAGE_ROOT/ssl/ssl_certificate.pem" -noout -fingerprint -sha256 | sed "s/SHA256 Fingerprint=//i"

Use the alias command to manage email forwarding aliases.

Available Alias Commands:

• alias: Lists all existing aliases.
• alias add <incoming_address> <destination_address>: Creates a new alias. The destination can be a single address or a comma-separated list of addresses wrapped in quotes.
• alias remove <incoming_address>: Removes an existing alias.

python3 management/cli.py alias add info@example.com 'person1@other.com, person2@other.com'
python3 management/cli.py alias remove info@example.com

During the initial installation, setup/start.sh creates a global executable at /usr/local/bin/mailinabox. This command allows you to re-run the configuration and setup process easily from any directory.

Note: The command is a wrapper that changes the working directory to the installation root and executes setup/start.sh.

sudo mailinabox