auctiora/docs/EMAIL_CONFIGURATION.md

# Email Notification Configuration Guide

## Overview
The application uses Gmail SMTP to send email notifications for auction alerts and lot updates.

## Gmail App Password Setup (Required for michael@appmodel.nl)

### Why App Passwords?
Google requires **App Passwords** instead of your regular Gmail password when using SMTP with 2-factor authentication enabled.

### Steps to Generate Gmail App Password:

1. **Enable 2-Factor Authentication** (if not already enabled)
   - Go to https://myaccount.google.com/security
   - Under "Signing in to Google", enable "2-Step Verification"

2. **Generate App Password**
   - Go to https://myaccount.google.com/apppasswords
   - Or navigate: Google Account → Security → 2-Step Verification → App passwords
   - Select app: "Mail"
   - Select device: "Other (Custom name)" → Enter "Auctiora Monitor"
   - Click "Generate"
   - Google will display a 16-character password (e.g., `abcd efgh ijkl mnop`)
   - **Copy this password immediately** (you won't see it again)

3. **Use the App Password**
   - Use this 16-character password (without spaces) in your configuration
   - Format: `abcdefghijklmnop`

## Configuration

### Method 1: Environment Variable (Recommended for Production)

Set the `auction.notification.config` property in your `application.properties` or via environment variable:

```properties
# Format: smtp:username:password:recipient_email
auction.notification.config=smtp:michael@appmodel.nl:YOUR_APP_PASSWORD:michael@appmodel.nl
```

**Example with Docker:**
```bash
docker run -e AUCTION_NOTIFICATION_CONFIG="smtp:michael@appmodel.nl:abcdefghijklmnop:michael@appmodel.nl" ...
```

### Method 2: application.properties (Development)

Edit `src/main/resources/application.properties`:

```properties
# BEFORE (desktop only):
auction.notification.config=desktop

# AFTER (desktop + email):
auction.notification.config=smtp:michael@appmodel.nl:YOUR_APP_PASSWORD_HERE:michael@appmodel.nl
```

### Format Breakdown

The configuration string format is:
```
smtp:<SMTP_USERNAME>:<APP_PASSWORD>:<RECIPIENT_EMAIL>
```

Where:
- `SMTP_USERNAME`: Your Gmail address (michael@appmodel.nl)
- `APP_PASSWORD`: The 16-character app password from Google (no spaces)
- `RECIPIENT_EMAIL`: Email address to receive notifications (can be same as sender)

## Configuration Examples

### Desktop Notifications Only
```properties
auction.notification.config=desktop
```

### Email Notifications Only
```properties
auction.notification.config=smtp:michael@appmodel.nl:abcdefghijklmnop:michael@appmodel.nl
```

### Both Desktop and Email (Recommended)
The SMTP configuration automatically enables both:
```properties
auction.notification.config=smtp:michael@appmodel.nl:abcdefghijklmnop:michael@appmodel.nl
```

### Send to Multiple Recipients
To send to multiple recipients, you can modify the code or set up Gmail forwarding rules.

## SMTP Configuration Details

The application uses these Gmail SMTP settings (hardcoded):
- **Host**: smtp.gmail.com
- **Port**: 587
- **Security**: STARTTLS
- **Authentication**: Required

## Testing Configuration

After configuration, restart the application and check logs:

**Success:**
```
✓ OpenCV loaded successfully
Email notification: Test Alert
```

**Failure (wrong password):**
```
WARN NotificationService - Email failed: 535-5.7.8 Username and Password not accepted
```

## Troubleshooting

### Error: "Username and Password not accepted"
- **Cause**: Invalid App Password or 2FA not enabled
- **Solution**:
  1. Verify 2-Factor Authentication is enabled
  2. Generate a new App Password
  3. Ensure no spaces in the password
  4. Check for typos in email address

### Error: "AuthenticationFailedException"
- **Cause**: Incorrect credentials format
- **Solution**: Verify the format: `smtp:user:pass:recipient`

### Gmail Blocks Sign-in
- **Cause**: "Less secure app access" is disabled (deprecated by Google)
- **Solution**: Use App Passwords (as described above)

### Configuration Not Taking Effect
- **Cause**: Application not restarted or environment variable not set
- **Solution**:
  1. Restart the application/container
  2. Verify with: `docker logs auctiora | grep notification`

### SMTP Connection Timeout
- **Error**: `Couldn't connect to host, port: smtp.gmail.com, 587; timeout -1`
- **Causes**:
  1. **Firewall/Network blocking port 587**
  2. **Corporate network blocking SMTP**
  3. **Antivirus/security software blocking connections**
  4. **No internet access in test/container environment**
- **Solutions**:
  1. **Test connectivity**:
     ```bash
     # On Linux/Mac
     telnet smtp.gmail.com 587
     # On Windows
     Test-NetConnection -ComputerName smtp.gmail.com -Port 587
     ```
  2. **Check firewall rules**: Allow outbound connections to port 587
  3. **Docker network**: Ensure container has internet access
     ```bash
     docker exec auctiora ping -c 3 smtp.gmail.com
     ```
  4. **Try alternative port 465** (SSL/TLS):
     - Requires code change to use `mail.smtp.socketFactory`
  5. **Corporate networks**: May require VPN or proxy configuration
  6. **Windows Firewall**: Add Java/application to allowed programs

### Connection Succeeds but Authentication Fails
- **Error**: `Email authentication failed - check Gmail App Password`
- **Solution**: Verify App Password is correct and has no spaces

## Security Best Practices

1. **Never commit passwords to git**
   - Use environment variables in production
   - Add `application-local.properties` to `.gitignore`

2. **Rotate App Passwords periodically**
   - Generate new App Password every 90 days
   - Revoke old passwords at https://myaccount.google.com/apppasswords

3. **Use separate App Passwords per application**
   - Creates "Auctiora Monitor" specific password
   - Easy to revoke if compromised

4. **Monitor Gmail Activity**
   - Check https://myaccount.google.com/notifications
   - Review "Recent security activity"

## Example Docker Compose Configuration

```yaml
services:
  auctiora:
    image: auctiora:latest
    environment:
      - AUCTION_NOTIFICATION_CONFIG=smtp:michael@appmodel.nl:${GMAIL_APP_PASSWORD}:michael@appmodel.nl
      - AUCTION_DATABASE_PATH=/mnt/okcomputer/output/cache.db
    volumes:
      - shared-auction-data:/mnt/okcomputer/output
```

Then set the password in `.env` file (not committed):
```bash
GMAIL_APP_PASSWORD=abcdefghijklmnop
```

## Notification Types

The application sends these email notifications:

1. **Lot Closing Soon** (Priority: High)
   - Sent when a lot closes within 5 minutes
   - Subject: `[Troostwijk] Lot nearing closure`

2. **Bid Updated** (Priority: Normal)
   - Sent when current bid increases
   - Subject: `[Troostwijk] Bid update`

3. **Critical Alerts** (Priority: High)
   - System errors or important events
   - Subject: `[Troostwijk] Critical Alert`

## Alternative: Desktop Notifications Only

If you don't want email notifications, use:
```properties
auction.notification.config=desktop
```

This will only show system tray notifications (Linux/Windows/Mac).