NewsAgent/CHANGES.md

# Changes for External Mail Server Support

This document summarizes the changes made to support external mail servers instead of local Postfix.

## Files Modified

### 1. `config.yaml`
- Updated SMTP section to use external mail server settings
- Changed default port from 25 to 587 (standard STARTTLS port)
- Enabled TLS by default
- Added comments explaining port and encryption options

**Before:**
```yaml
smtp:
  host: "localhost"
  port: 25
  use_tls: false
  use_ssl: false
```

**After:**
```yaml
smtp:
  host: "mail.yourdomain.com"
  port: 587  # Standard SMTP submission port (use 465 for SSL)
  use_tls: true  # Use STARTTLS (for port 587)
  use_ssl: false  # Set to true if using port 465
  # Username and password are loaded from .env file for security
```

### 2. `.env.example`
- Added SMTP_USERNAME field
- Added SMTP_PASSWORD field
- Added documentation for SMTP credentials

**Added:**
```env
# SMTP Credentials for your mail server
SMTP_USERNAME=your-email@yourdomain.com
SMTP_PASSWORD=your-smtp-password
```

### 3. `src/config.py`
- Added `smtp_username` field to `EnvSettings` class
- Added `smtp_password` field to `EnvSettings` class
- Modified `Config.email` property to merge SMTP credentials from environment variables into email configuration

**Changes:**
- Environment variables now include SMTP credentials
- SMTP credentials are automatically loaded from `.env` and merged into config
- Keeps passwords secure (not in config.yaml)

### 4. `README.md`
- Removed Postfix installation instructions
- Updated prerequisites to mention "SMTP Server" instead of Postfix
- Added SMTP configuration examples for various providers
- Updated configuration steps to include SMTP credentials
- Renumbered installation steps (removed Postfix step)

### 5. `SETUP.md`
- Removed Postfix installation and configuration sections
- Updated system requirements (no Postfix needed)
- Added SMTP credentials to `.env` configuration
- Updated email configuration section with SMTP examples
- Updated verification checklist
- Updated troubleshooting section for SMTP issues

## New Files Added

### 6. `SMTP_CONFIG.md`
Comprehensive guide for configuring SMTP with:
- Step-by-step setup instructions
- Common mail server configurations (Gmail, Outlook, SendGrid, etc.)
- Port and encryption guide (587 vs 465 vs 25)
- Testing procedures
- Troubleshooting common SMTP errors
- Security best practices
- Example working configurations

## How It Works

### Configuration Flow

1. **User creates `.env` file** with SMTP credentials:
   ```env
   SMTP_USERNAME=user@domain.com
   SMTP_PASSWORD=password
   ```

2. **User edits `config.yaml`** with mail server settings:
   ```yaml
   smtp:
     host: "mail.domain.com"
     port: 587
     use_tls: true
   ```

3. **Application loads configuration**:
   - `EnvSettings` loads SMTP credentials from `.env`
   - `Config` loads mail server settings from `config.yaml`
   - `Config.email` property merges them together

4. **Email sender uses merged configuration**:
   - `EmailSender` receives complete SMTP config
   - Connects to external mail server
   - Authenticates with username/password
   - Sends email via authenticated SMTP

### Security Benefits

- **Credentials separated from code**: SMTP passwords in `.env` (gitignored)
- **Mail server settings in config**: Non-sensitive info in `config.yaml`
- **No local mail server needed**: Simpler setup, fewer services to maintain
- **Industry standard**: Works with any SMTP provider

## What Users Need to Do

### Required Changes

1. **Update `.env` file**:
   ```bash
   cp .env.example .env
   nano .env
   ```
   Add:
   ```env
   SMTP_USERNAME=your-email@domain.com
   SMTP_PASSWORD=your-password
   ```

2. **Update `config.yaml`**:
   ```bash
   nano config.yaml
   ```
   Change email section:
   ```yaml
   email:
     to: "recipient@example.com"
     from: "sender@domain.com"
     smtp:
       host: "mail.domain.com"
       port: 587
       use_tls: true
       use_ssl: false
   ```

### No Longer Needed

- Postfix installation
- Postfix configuration
- Local mail server maintenance
- Mail relay setup

## Testing

To test the new configuration:

```bash
# 1. Set up credentials
cp .env.example .env
nano .env  # Add SMTP credentials

# 2. Configure mail server
nano config.yaml  # Update SMTP settings

# 3. Test run
source .venv/bin/activate
python -m src.main

# 4. Check logs
tail -f data/logs/news-agent.log
```

## Backward Compatibility

The system still supports local mail servers if needed:

**For local Postfix:**
```yaml
smtp:
  host: "localhost"
  port: 25
  use_tls: false
  use_ssl: false
```

No credentials needed in `.env` for localhost delivery.

## Common Use Cases

### 1. Personal Mail Server
User runs their own mail server at `mail.example.com`:
- Authenticate with their email credentials
- Use standard port 587 with TLS
- Most common use case

### 2. Gmail for Testing
User wants to test with Gmail:
- Create App Password in Google account
- Use `smtp.gmail.com:587`
- Quick setup for development/testing

### 3. Commercial SMTP Service
User has SendGrid/Mailgun subscription:
- Use service's SMTP credentials
- Higher reliability and deliverability
- Good for production use

## Documentation Structure

Users should read in this order:

1. **README.md** - Overview and quick start
2. **SETUP.md** - Step-by-step installation
3. **SMTP_CONFIG.md** - Detailed SMTP configuration (if issues)
4. **CHANGES.md** - This file (if migrating from old version)