IMAP & SMTP Configuration

Opterius Mail connects to an IMAP server for reading mail and an SMTP server for sending. Both are configured via .env variables, which override the defaults in config/imap.php and config/smtp.php. This article covers all common deployment scenarios.

IMAP Configuration#

IMAP settings control how Opterius Mail connects to the mail server to read and manage messages. The underlying library is webklex/php-imap v5.

Local Dovecot (Standard — Opterius Panel Install)#

When installed alongside Opterius Panel, Dovecot runs on the same server and uses a self-signed TLS certificate.

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

IMAP_VALIDATE_CERT=false is required here because Dovecot's self-signed certificate will not pass standard CA validation. This is safe in a loopback connection.

Local Dovecot with STARTTLS#

If your Dovecot is configured for STARTTLS on port 143 instead of IMAPS on 993:

IMAP_HOST=127.0.0.1
IMAP_PORT=143
IMAP_ENCRYPTION=tls
IMAP_VALIDATE_CERT=false

Remote IMAP Server (Company Mail Server)#

For a remote server with a valid TLS certificate:

IMAP_HOST=mail.company.com
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=true

Gmail#

Users authenticate with their Google account credentials. If the account uses Google 2FA, they must create an App Password in Google Account → Security → App Passwords, and use that instead of their regular Google password.

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

Note: Google requires OAuth2 for new app integrations since 2024. Basic IMAP authentication (username + app password) continues to work for GSuite/Workspace accounts with the "Allow less secure apps" setting or via app passwords.

Microsoft Office 365 / Exchange Online#

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

Modern Authentication (OAuth2) may be required for Office 365 tenants that have disabled Basic Authentication. In that case, Opterius Mail's standard IMAP auth will not work — OAuth2 support requires a custom plugin.

Fastmail#

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

Username Suffix#

Some IMAP servers require the full email address for authentication (user@domain.com) while others require only the local part (user). If your server requires the full email address and users log in with just the local part, use:

IMAP_USERNAME_SUFFIX=@yourdomain.com

Opterius Mail appends this to the entered username before attempting IMAP authentication. Leave blank when users enter their full email address on the login form.

Testing IMAP Connection#

Use the Artisan test command to verify your IMAP settings:

cd /opt/opterius-mail

# Test IMAP connectivity and authentication
php artisan mail:test-imap user@example.com yourpassword

Expected output on success:

IMAP connection successful.
Logged in as: user@example.com
Folders found: INBOX, Sent, Drafts, Trash, Spam

On failure, the command prints the IMAP error string from the server, which is usually sufficient to diagnose the problem.

SMTP Configuration#

SMTP settings control how Opterius Mail sends outgoing messages (composed mail, autoresponders, admin notifications).

Local Postfix (Standard — Opterius Panel Install)#

MAIL_HOST=127.0.0.1
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=
MAIL_PASSWORD=

Port 587 with STARTTLS is the submission port. Postfix on localhost does not require SMTP authentication for connections from 127.0.0.1 (configured via mynetworks in main.cf), so MAIL_USERNAME and MAIL_PASSWORD are left blank.

Alternatively, using port 25 directly to Postfix:

MAIL_HOST=127.0.0.1
MAIL_PORT=25
MAIL_ENCRYPTION=none

External SMTP Relay (SendGrid, Mailgun, etc.)#

MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-sendgrid-api-key

For Mailgun:

MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=postmaster@yourdomain.mailgun.org
MAIL_PASSWORD=your-mailgun-smtp-password

Office 365 SMTP#

MAIL_HOST=smtp.office365.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=user@yourdomain.com
MAIL_PASSWORD=app-password-or-account-password

Gmail SMTP#

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=user@gmail.com
MAIL_PASSWORD=your-app-password

Testing SMTP#

cd /opt/opterius-mail

# Send a test message
php artisan mail:test-smtp recipient@example.com

This sends a plain-text test message using the current .env SMTP settings and reports the SMTP server's response.

Diagnosing SMTP Issues#

# Manual SMTP test from the command line
swaks --to recipient@example.com \
      --from sender@yourdomain.com \
      --server 127.0.0.1 \
      --port 587 \
      --tls

# Check Postfix is listening
ss -tlnp | grep :587

# Check Postfix queue for errors
mailq

config/imap.php Advanced Options#

For settings not covered by .env variables, edit config/imap.php directly:

return [
    'default' => [
        'host'          => env('IMAP_HOST', '127.0.0.1'),
        'port'          => (int) env('IMAP_PORT', 993),
        'encryption'    => env('IMAP_ENCRYPTION', 'ssl'),
        'validate_cert' => (bool) env('IMAP_VALIDATE_CERT', false),
        'username'      => null,   // Set per-user at auth time
        'password'      => null,   // Set per-user at auth time
        'authentication'=> 'plain',
        'proxy'         => [
            'socket'   => null,
            'request'  => null,
            'username' => null,
            'password' => null,
        ],
        'timeout'       => 30,     // IMAP connection timeout in seconds
        'extensions'    => [],     // Custom IMAP extensions
    ],
];

After editing a config file (not .env), run:

php artisan config:clear