minio-webui/EMAIL_CONFIGURATION.md

Email Configuration Guide for MinIO WebUI

Overview

MinIO WebUI supports email notifications for storage reports. This guide explains how to configure email settings, especially for Microsoft Exchange servers.

Environment Variables

Configure these variables in your .env file:

With Authentication (Most servers)

# SMTP Server Configuration
SMTP_HOST=your-exchange-server.com
SMTP_PORT=25
SMTP_SECURE=false
SMTP_USER=your-username
SMTP_PASS=your-password

# Email Settings
REPORT_SENDER=minio-reports@yourdomain.com
REPORT_RECIPIENT=admin@yourdomain.com

# Report Schedule (cron format)
REPORT_SCHEDULE=0 0 * * 1  # Every Monday at midnight

Without Authentication (Open Relay/Internal Exchange)

# SMTP Server Configuration
SMTP_HOST=exchange.internal.company.com
SMTP_PORT=25
SMTP_SECURE=false
# Leave SMTP_USER and SMTP_PASS empty or don't include them
SMTP_USER=
SMTP_PASS=

# Email Settings
REPORT_SENDER=minio-reports@yourdomain.com
REPORT_RECIPIENT=admin@yourdomain.com

# Report Schedule (cron format)
REPORT_SCHEDULE=0 0 * * 1  # Every Monday at midnight

Port and Security Settings

Port 25 (No TLS/SSL)

Most common for internal Exchange servers:

SMTP_PORT=25
SMTP_SECURE=false

Port 587 (STARTTLS)

For servers that support encryption:

SMTP_PORT=587
SMTP_SECURE=false  # STARTTLS will upgrade the connection

Port 465 (SSL/TLS)

For servers requiring SSL from the start:

SMTP_PORT=465
SMTP_SECURE=true

Common Issues and Solutions

Self-Signed Certificate Error

Error: self-signed certificate

Solution: The application is configured to accept self-signed certificates. If you still see this error:

1. Ensure SMTP_SECURE=false for port 25
2. Restart the backend service
3. Check that your Exchange server allows SMTP connections on port 25

Connection Refused

Error: connect ECONNREFUSED

Solution:

1. Verify the SMTP_HOST is correct
2. Check if port 25 is open on the Exchange server
3. Ensure no firewall is blocking the connection

Authentication Failed

Error: Invalid login or Unrecognized authentication type

Solution:

1. If your Exchange server doesn't require authentication (internal relay):
   • Leave SMTP_USER and SMTP_PASS empty in your .env file
   • Or remove these variables entirely
2. If authentication is required, verify credentials:
   • Username only: username
   • Domain\Username: DOMAIN\\username
   • Email format: username@domain.com

Exchange Server Specific Settings

For Microsoft Exchange servers, the configuration automatically:

• Accepts self-signed certificates when SMTP_SECURE=false
• Disables TLS for port 25 when SMTP_SECURE=false
• Handles STARTTLS negotiation for port 587

Testing Email Configuration

1. Set up your environment variables
2. Restart the backend:

   docker-compose restart backend
   

3. Check the logs:

   docker logs minio-webui-backend -f
   

4. Look for either:
   • ✅ Email transporter ready
   • ❌ Email transporter verification failed

Manual Test

To manually trigger a test email:

1. Log into the MinIO WebUI
2. Navigate to Reports
3. Click "E-Mail senden" (Send Email)

Report Schedule Format

The REPORT_SCHEDULE uses cron format:

┌────────────── second (optional)
│ ┌──────────── minute
│ │ ┌────────── hour
│ │ │ ┌──────── day of month
│ │ │ │ ┌────── month
│ │ │ │ │ ┌──── day of week
│ │ │ │ │ │
* * * * * *

Examples:

• 0 0 * * 1 - Every Monday at midnight
• 0 8 * * * - Every day at 8 AM
• 0 0 1 * * - First day of every month at midnight
• 0 */6 * * * - Every 6 hours

Troubleshooting

Enable Debug Logging

Add to your .env:

LOG_LEVEL=debug

Check Email Service Status

# View recent logs
docker logs minio-webui-backend --tail 50

# Watch logs in real-time
docker logs minio-webui-backend -f

Common Exchange Configurations

Internal Exchange (No Auth):

SMTP_HOST=exchange.internal.company.com
SMTP_PORT=25
SMTP_SECURE=false
SMTP_USER=
SMTP_PASS=

Exchange with Auth:

SMTP_HOST=mail.company.com
SMTP_PORT=25
SMTP_SECURE=false
SMTP_USER=DOMAIN\\username
SMTP_PASS=yourpassword

Office 365:

SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=user@company.com
SMTP_PASS=yourpassword

Security Considerations

1. Store credentials securely in .env file
2. Never commit .env to version control
3. Use application-specific passwords when available
4. Consider using OAuth2 for modern email services
5. Restrict SMTP relay access on Exchange server

Need Help?

If email configuration continues to fail:

1. Verify with your IT team that SMTP is enabled on the Exchange server
2. Check if any additional authentication (like NTLM) is required
3. Test connectivity: telnet your-exchange-server 25
4. Review Exchange server logs for connection attempts