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)
```bash
# 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)
```bash
# 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:
```bash
SMTP_PORT=25
SMTP_SECURE=false
```

### Port 587 (STARTTLS)
For servers that support encryption:
```bash
SMTP_PORT=587
SMTP_SECURE=false  # STARTTLS will upgrade the connection
```

### Port 465 (SSL/TLS)
For servers requiring SSL from the start:
```bash
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:
   ```bash
   docker-compose restart backend
   ```
3. Check the logs:
   ```bash
   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`:
```bash
LOG_LEVEL=debug
```

### Check Email Service Status

```bash
# 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)**:
```bash
SMTP_HOST=exchange.internal.company.com
SMTP_PORT=25
SMTP_SECURE=false
SMTP_USER=
SMTP_PASS=
```

**Exchange with Auth**:
```bash
SMTP_HOST=mail.company.com
SMTP_PORT=25
SMTP_SECURE=false
SMTP_USER=DOMAIN\\username
SMTP_PASS=yourpassword
```

**Office 365**:
```bash
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