Connecting to Your Mail Server

Opterius Mail is a webmail front-end — it relies on your existing IMAP server to read mail and your SMTP server to send it. This page explains how to configure both connections correctly.

IMAP Configuration#

Environment Variables#

The primary IMAP settings live in your .env file:

IMAP_HOST=127.0.0.1
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=true

config/imap.php#

Opterius Mail uses webklex/php-imap for IMAP communication. The library's configuration is published to config/imap.php. You generally do not need to edit this file directly — the .env variables above feed into it automatically — but it is useful to understand for advanced setups:

'accounts' => [
    'default' => [
        'host'          => env('IMAP_HOST', '127.0.0.1'),
        'port'          => env('IMAP_PORT', 993),
        'encryption'    => env('IMAP_ENCRYPTION', 'ssl'),
        'validate_cert' => env('IMAP_VALIDATE_CERT', true),
        'username'      => null, // set per-session at login time
        'password'      => null, // set per-session at login time
        'protocol'      => 'imap',
    ],
],

At login, Opterius Mail injects the user's email address and password into this connection at runtime — there is no shared service account.

SMTP Configuration#

SMTP is used when sending messages. Configure it in .env:

MAIL_HOST=127.0.0.1
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_FROM_NAME="Opterius Mail"

SMTP credentials are supplied per-session using the logged-in user's IMAP username and password. Opterius Mail does not use a separate SMTP service account.

Common Setups#

Dovecot on Localhost (Recommended)#

The most common setup when running Opterius Mail on the same server as Dovecot + Postfix:

IMAP_HOST=127.0.0.1
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=false   # set to true if you have a valid cert for localhost

MAIL_HOST=127.0.0.1
MAIL_PORT=587
MAIL_ENCRYPTION=tls

Setting IMAP_VALIDATE_CERT=false is acceptable for localhost connections where you are using a self-signed certificate (which is typical for Dovecot installed by Opterius Panel).

Remote IMAP Server#

If your IMAP server is on a different machine:

IMAP_HOST=imap.yourdomain.com
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=true

MAIL_HOST=smtp.yourdomain.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls

Ensure port 993 is reachable from your Opterius Mail server (check firewalls on both sides).

Microsoft Exchange / Office 365#

IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=true

MAIL_HOST=smtp.office365.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls

Note: Office 365 requires Modern Authentication (OAuth2) for some tenant configurations. If your tenant has disabled Basic Auth for IMAP, Opterius Mail will not be able to authenticate. Check your Microsoft 365 admin center under Security → Authentication policies.

Gmail (G Suite / Google Workspace)#

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=true

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls

Note: Personal Gmail accounts require an App Password (not your regular Google password) because Google blocks Basic Auth for standard accounts. Google Workspace accounts with IMAP enabled and Basic Auth allowed work without App Passwords.

Clearing Configuration Cache#

After changing .env, always clear Laravel's config cache:

php artisan config:clear
php artisan config:cache

Troubleshooting Connection Failures#

Check the Laravel log#

tail -f /opt/opterius-mail/storage/logs/laravel.log

Common errors and their causes:

Test IMAP Connectivity Manually#

From the Opterius Mail server, test TCP connectivity:

nc -zv 127.0.0.1 993

Test IMAP authentication directly with openssl:

openssl s_client -connect 127.0.0.1:993
# After connection, type:
a1 LOGIN user@example.com yourpassword

If this succeeds in the terminal but fails in Opterius Mail, the issue is in .env configuration, not the mail server.

Test SMTP#

nc -zv 127.0.0.1 587

For a full SMTP test:

php artisan tinker
>>> Mail::raw('test', fn($m) => $m->to('test@example.com')->subject('test'));