Admin

Enabling Admin Mode

How to enable admin mode in Opterius Mail to unlock full domain, account, alias, and DKIM management.

Last updated 2026-04-12
  • What Admin Mode Adds
  • Verifying the Change
  • Disabling Admin Mode

    • Enabling Admin Mode

    Admin mode is disabled by default in Opterius Mail. In its default state the application functions as a webmail-only client: users log in with their IMAP credentials and interact with their mailbox, but there is no interface for creating accounts, managing domains, configuring DKIM, or inspecting the mail queue. Admin mode unlocks all of that.

    When You Need Admin Mode

    You need admin mode enabled if you are running Opterius Mail as the mail management layer for a hosting environment — either standalone against your own Dovecot/Postfix stack, or alongside Opterius Panel. In these configurations Opterius Mail owns the mail_accounts and mail_domains database tables that Dovecot and Postfix read from for authentication and routing.

    If you are deploying Opterius Mail purely as a webmail front-end against an existing, externally managed mail server (for example a corporate Exchange or a cPanel mail server), you do not need admin mode and should leave it disabled.

    When installed with Opterius Panel: the installer enables admin mode automatically and sets MAIL_ADMIN=true in your .env. You do not need to do anything manually.

    Enabling Admin Mode Manually

    Step 1 — Edit .env

    Open /opt/opterius-mail/.env in your editor and set:

    MAIL_ADMIN=true

    If the key does not exist yet, add it anywhere in the file. The default value (when the key is absent) is false.

    Step 2 — Run Database Migrations

    Admin mode introduces several additional database tables:

    Table Purpose
    admins Admin user accounts (separate from email accounts)
    mail_domains Domains managed by this installation
    mail_accounts Email accounts, synced from Panel agent or created manually
    mail_aliases Address aliases mapped to destinations
    mail_groups Group/distribution addresses
    dkim_keys Per-domain DKIM key pairs
    autoresponders Autoresponder rules per account
    user_two_factor Webmail 2FA settings for email users

    Run migrations as the application user:

    cd /opt/opterius-mail
php artisan migrate

    If you are running in production and want to confirm the migration plan before applying it, use the --pretend flag first:

    php artisan migrate --pretend

    Step 3 — Restart the Application

    If you are running Opterius Mail under PHP-FPM or a process manager, reload it so the new configuration is picked up:

    # PHP-FPM
sudo systemctl reload php8.2-fpm

# Or if running via artisan serve (development only)
# Stop and restart the process

    If you are using OPcache in production, clear it:

    php artisan opcache:clear 2>/dev/null || true

    What Admin Mode Adds

    Once enabled, the following become available:

    • /admin route — the full admin panel (separate login from webmail)
    • /admin/setup — first-time admin account creation (only accessible before any admin exists)
    • Domain management — add/edit/delete mail domains
    • Account management — create/edit/delete email accounts; view sync status from Panel
    • Alias and group management — configure address routing
    • DKIM management — generate RSA key pairs, view DNS records, verify propagation
    • Spam management — Rspamd statistics and training controls (when Rspamd is configured)
    • Mail queue — view Postfix queue, retry or delete queued messages
    • Log viewer — tail and filter /var/log/mail.log
    • Sync API endpoint — POST /api/sync/account becomes active (Panel agent uses this)

    Verifying the Change

    After restarting, visit http://your-server:8090/admin. You should be redirected to /admin/setup (if no admin account exists yet) or to the login page (if one already exists). A 404 response at /admin means MAIL_ADMIN is still false or the configuration was not reloaded.

    Disabling Admin Mode

    Set MAIL_ADMIN=false and reload. The admin routes and the sync API endpoint are no longer registered. The database tables remain intact — re-enabling admin mode will restore full functionality without data loss.

    Note: Disabling admin mode does not stop Dovecot from reading mail_accounts for authentication. Mail delivery continues normally; you just lose the management UI.

    Next
    First Admin Setup →