Export & Backup Configuration

Opterius Mail stores configuration in two places: the MySQL database (domains, accounts, aliases, DKIM records, autoresponders) and the filesystem (DKIM private keys, Maildir email data). A complete backup strategy must cover both.

Admin Panel Export#

Admin → Settings → Export provides quick exports of structured configuration data.

Export Domains and Accounts (JSON)#

Downloads a JSON file containing all domains and their associated accounts, aliases, groups, and autoresponder rules. This is the primary format for migrating configuration to another server.

Example structure:

{
  "exported_at": "2026-04-12T14:00:00Z",
  "domains": [
    {
      "domain": "example.com",
      "catch_all": "admin@example.com",
      "accounts": [
        {
          "email": "jane@example.com",
          "quota_mb": 1024,
          "status": "active"
        }
      ],
      "aliases": [
        {
          "alias": "info@example.com",
          "destination": "jane@example.com"
        }
      ]
    }
  ]
}

Note: passwords are not included in the export for security reasons. After importing to a new server, passwords must be re-synced from the Panel (in panel-integrated mode) or reset manually.

Export DKIM Keys (tar archive)#

Downloads a .tar.gz archive containing all DKIM private keys and their associated metadata (domain, selector). Use this to restore DKIM signing on a new server without regenerating keys and updating DNS records.

The archive structure:

dkim-keys-export-2026-04-12.tar.gz
├── example.com/
│   ├── mail.private     (RSA private key)
│   ├── mail.public      (RSA public key)
│   └── mail.txt         (DNS TXT record value, for reference)
└── anotherdomain.com/
    └── ...

Export Aliases and Groups (JSON)#

Downloads alias and group configuration separately. Useful for documentation or for bulk editing outside the application.

Database Backup#

The database is the source of truth for all Opterius Mail configuration. Back it up regularly with mysqldump:

# Full database backup
mysqldump -u opterius_mail -p opterius_mail > /backups/opterius-mail-$(date +%Y%m%d).sql

# Compressed backup
mysqldump -u opterius_mail -p opterius_mail | gzip > /backups/opterius-mail-$(date +%Y%m%d).sql.gz

For automated daily backups, add to cron:

# /etc/cron.d/opterius-mail-backup
0 2 * * * root mysqldump -u opterius_mail -p'yourpassword' opterius_mail | gzip > /backups/opterius-mail-$(date +\%Y\%m\%d).sql.gz

Keep the last 7–30 days of database backups depending on your retention policy.

Maildir Backup#

Email data is stored in Maildir format on the filesystem:

/var/mail/{domain}/{user}/Maildir/

Back this up with rsync:

# Incremental sync to a backup location
rsync -avz --delete /var/mail/ /backups/maildir/

# Or to a remote server
rsync -avz --delete /var/mail/ backup-user@backup-server:/backups/maildir/

For large mail stores, consider rsync --checksum to detect changes by content rather than modification time.

Maildir is safe to rsync while Dovecot is running because each message is a separate file. No files are partially written during a sync.

Restore Procedure#

1. Restore the Database#

# Create the database if it does not exist
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS opterius_mail;"

# Import the backup
mysql -u root -p opterius_mail < /backups/opterius-mail-20260412.sql

2. Restore DKIM Keys#

Extract the DKIM archive and copy keys to the correct location:

tar -xzf dkim-keys-export-2026-04-12.tar.gz -C /tmp/dkim-restore/

# Copy to OpenDKIM directory
cp -r /tmp/dkim-restore/*/ /etc/opendkim/keys/
chown -R opendkim:opendkim /etc/opendkim/keys/
chmod 600 /etc/opendkim/keys/*/*.private

sudo systemctl reload opendkim

3. Restore Maildir#

rsync -avz /backups/maildir/ /var/mail/
chown -R vmail:vmail /var/mail/

4. Re-import Domain/Account JSON (optional)#

If the database backup was unavailable but you have a JSON export, use the Artisan import command:

cd /opt/opterius-mail
php artisan mail:import /path/to/export.json

Or via the admin panel: Admin → Settings → Import.

5. Re-sync from Panel (panel-integrated mode)#

If the installation is integrated with Opterius Panel, passwords do not need to be restored manually. After the database is restored, trigger a full re-sync from the Panel:

# On the Panel server — forces the agent to re-sync all accounts
opterius-agent resync-mail

All account passwords, domains, and aliases will be re-synced from the Panel's authoritative data. Only DKIM keys and any manually created configuration (aliases, groups that were not created in the Panel) need to be restored from backup.