Mail-in-a-Box Simple Mail Server

Mail-in-a-Box turns a fresh Ubuntu VPS into a fully configured mail server with DNS, webmail, contacts, and calendar in a single automated setup. This guide covers installing Mail-in-a-Box, configuring DNS, accessing webmail, enabling contact/calendar sync, and maintaining your server.

Prerequisites

• Ubuntu 22.04 LTS (required - Mail-in-a-Box is strict about supported OS)
• A fresh server with no other software installed
• Minimum 512 MB RAM (1 GB+ recommended)
• A domain name you control (e.g., yourdomain.com)
• Static IP address
• Ports 25, 53, 80, 443, 587, 993, 995 accessible
• Root access

Mail-in-a-Box is designed as a turnkey solution - do not install other software on the same server.

DNS Pre-Configuration

Set two DNS records before installation:

1. A record: Point your mail hostname to your server IP

   • Name: box.yourdomain.com
   • Value: YOUR_SERVER_IP

2. PTR/Reverse DNS: Set in your VPS control panel

   • IP: YOUR_SERVER_IP → box.yourdomain.com

These are the only records needed before installation. Mail-in-a-Box will tell you all additional records to add after setup.

Set your server hostname before installing:

sudo hostnamectl set-hostname box.yourdomain.com
hostname  # Verify

Installing Mail-in-a-Box

# Update system
sudo apt update && sudo apt upgrade -y

# Run the installation script
curl -s https://mailinabox.email/setup.sh | sudo -E bash

The installer will prompt for:

1. Email address: Your primary admin email (e.g., [email protected])
2. Hostname: box.yourdomain.com (should be pre-filled from hostnamectl)

The installation takes 15-30 minutes and sets up:

• Postfix (SMTP)
• Dovecot (IMAP/POP3)
• Roundcube (webmail)
• Nextcloud (contacts/calendar)
• Nginx (web server)
• Let's Encrypt SSL
• rspamd (spam filtering)
• BIND DNS server

At the end, it displays the admin password - save it immediately.

Post-Installation DNS Setup

After installation, the admin panel shows all required DNS records:

https://box.yourdomain.com/admin#system_dns

You'll need to add records at your domain registrar:

If you want Mail-in-a-Box to manage its own DNS (recommended for simplicity):

1. Point your domain's nameservers to:
   • ns1.box.yourdomain.com
   • ns2.box.yourdomain.com
2. Add glue records at your registrar pointing to your server IP

Verify DNS propagation:

dig MX yourdomain.com @8.8.8.8
dig TXT yourdomain.com @8.8.8.8

Accessing the Admin Panel and Webmail

• Admin panel: https://box.yourdomain.com/admin
  • Login with your email and the generated admin password
• Webmail (Roundcube): https://box.yourdomain.com/mail
  • Login with your full email and password

The admin panel shows the System Status Checks page - all checks should be green before going live. Common items to resolve:

• Reverse DNS not set (requires VPS provider support)
• Firewall blocking ports
• DNS records not yet propagated

Adding Users and Aliases

Via the admin panel:

1. Mail > Users > Add a Mail User
2. Enter email address and password

Via the command line:

# Add a user
sudo mailinabox/management/cli.py user add [email protected] password123

# List users
sudo mailinabox/management/cli.py user list

# Add an alias (forward)
sudo mailinabox/management/cli.py alias add [email protected] [email protected]

# Remove a user
sudo mailinabox/management/cli.py user remove [email protected]

Or use the REST API:

# Get API key from Admin > Mail > Users > Set Password (generates a token)
curl -X POST "https://box.yourdomain.com/admin/mail/users/add" \
  -u [email protected]:ADMIN_PASSWORD \
  -d "[email protected]&password=StrongPass123"

Contact and Calendar Sync

Mail-in-a-Box includes Nextcloud for contact and calendar synchronization:

• Nextcloud URL: https://box.yourdomain.com/cloud
• Login with your email and mail password

Configure mobile/desktop sync:

Android (DAVx5):

1. Install DAVx5 from F-Droid or Play Store
2. Add account: Base URL = https://box.yourdomain.com/cloud

iOS:

1. Settings > Mail > Accounts > Add Account > Other
2. Add CardDAV/CalDAV account
3. Server: box.yourdomain.com

macOS/Windows (Thunderbird):

• Thunderbird auto-discovers the account via autodiscover
• Or manually add IMAP: box.yourdomain.com, port 993, SSL

Backup Configuration

Mail-in-a-Box backs up automatically to /home/user-data/backup/. Configure remote backups via the admin panel:

Admin > System > Backup

Options:

• Local (default) - stored on the server
• S3 - Amazon S3 or compatible (MinIO, Backblaze B2)
• RSYNC - to a remote SSH server

For S3-compatible backup:

Target: s3://bucket-name/prefix/
AWS Access Key: your_key
AWS Secret Key: your_secret

Manual backup:

sudo mailinabox/management/backup.py
ls -la /home/user-data/backup/encrypted/

Maintenance and Updates

# Update Mail-in-a-Box
sudo mailinabox/setup/start.sh

# Or run the setup script again (safe to re-run)
curl -s https://mailinabox.email/setup.sh | sudo -E bash

# Check system status
sudo mailinabox/management/status_checks.py

# Renew Let's Encrypt certificates manually
sudo certbot renew

Monitor the system:

# Check mail queue
sudo postqueue -p

# Flush stuck mail
sudo postqueue -f

# Check rspamd spam stats
sudo rspamc stat

# View mail logs
sudo tail -f /var/log/mail.log

Troubleshooting

"Mail server is not configured correctly" in status checks:

Follow each failing check item in the admin panel - most have direct instructions. Common fixes:

# Verify all ports are accessible
nc -zv your-server-ip 25
nc -zv your-server-ip 993

# Check firewall
sudo ufw status

Emails going to spam:

# Verify PTR record
dig -x YOUR_SERVER_IP +short

# Check all DNS records are correct in the admin panel
# Use mail-tester.com to send a test email and get a score

Can't receive mail:

# Check if postfix is listening
ss -tlnp | grep ':25'

# Check mail log for errors
sudo grep -i error /var/log/mail.log | tail -20

# Check the mail queue
sudo postqueue -p

SSL certificate errors:

# Force certificate renewal
sudo certbot renew --force-renewal
sudo service nginx reload

Conclusion

Mail-in-a-Box is the fastest way to get a fully configured, self-hosted mail server running on Ubuntu. Its automated DNS guidance, integrated webmail, and Nextcloud contacts/calendar sync make it suitable for personal use and small organizations. Re-run the setup script after Ubuntu upgrades or to apply Mail-in-a-Box updates, and monitor the System Status panel regularly to keep everything green.