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:

smtp:
  host: "localhost"
  port: 25
  use_tls: false
  use_ssl: false

After:

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:

# 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:

   SMTP_USERNAME=user@domain.com
   SMTP_PASSWORD=password
   

2. User edits config.yaml with mail server settings:

   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:

   cp .env.example .env
   nano .env
   

   Add:

   SMTP_USERNAME=your-email@domain.com
   SMTP_PASSWORD=your-password
   

2. Update config.yaml:

   nano config.yaml
   

   Change email section:

   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:

# 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:

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)