NewsAgent/SMTP_CONFIG.md

SMTP Configuration Guide

This guide helps you configure News Agent to work with your mail server.

Configuration Overview

News Agent needs two pieces of configuration:

1. SMTP credentials in .env file (secure)
2. SMTP server settings in config.yaml (non-sensitive)

Step-by-Step Setup

1. Edit .env file

nano .env

Add your SMTP credentials:

SMTP_USERNAME=your-email@yourdomain.com
SMTP_PASSWORD=your-password-or-app-password

Security Note: The .env file is gitignored and should never be committed to version control.

2. Edit config.yaml

nano config.yaml

Update the SMTP section under email:

email:
  to: "recipient@example.com"  # Where to send the digest
  from: "sender@yourdomain.com"  # From address (usually same as SMTP_USERNAME)
  from_name: "Daily Tech News Agent"
  subject_template: "Tech News Digest - {date}"
  smtp:
    host: "mail.yourdomain.com"  # Your SMTP server hostname
    port: 587  # See port guide below
    use_tls: true  # See TLS/SSL guide below
    use_ssl: false

Common Mail Server Configurations

Your Own Mail Server

If you run your own mail server (Postfix, Exim, etc.):

smtp:
  host: "mail.yourdomain.com"
  port: 587  # Standard submission port
  use_tls: true
  use_ssl: false

SMTP_USERNAME=your-email@yourdomain.com
SMTP_PASSWORD=your-actual-password

Gmail

Important: Gmail requires an App Password, not your regular password.

Generate App Password:

1. Go to https://myaccount.google.com/security
2. Enable 2-factor authentication
3. Go to App Passwords
4. Generate password for "Mail"

smtp:
  host: "smtp.gmail.com"
  port: 587
  use_tls: true
  use_ssl: false

SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-16-char-app-password

Outlook / Office 365

smtp:
  host: "smtp.office365.com"
  port: 587
  use_tls: true
  use_ssl: false

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

SendGrid

smtp:
  host: "smtp.sendgrid.net"
  port: 587
  use_tls: true
  use_ssl: false

SMTP_USERNAME=apikey
SMTP_PASSWORD=your-sendgrid-api-key

Mailgun

smtp:
  host: "smtp.mailgun.org"
  port: 587
  use_tls: true
  use_ssl: false

SMTP_USERNAME=postmaster@your-domain.mailgun.org
SMTP_PASSWORD=your-mailgun-smtp-password

Port and Encryption Guide

Port 587 (Recommended)

• Protocol: STARTTLS
• Settings: port: 587, use_tls: true, use_ssl: false
• Use case: Most modern SMTP servers
• Security: Connection starts unencrypted, then upgrades to TLS

Port 465

• Protocol: SMTPS (SMTP over SSL)
• Settings: port: 465, use_tls: false, use_ssl: true
• Use case: Legacy SSL connections
• Security: Encrypted from the start

Port 25

• Protocol: Plain SMTP
• Settings: port: 25, use_tls: false, use_ssl: false
• Use case: Local mail servers only (not recommended for internet)
• Security: Unencrypted (only use on localhost)

Testing Your Configuration

Test 1: Manual Run

cd ~/news-agent
source .venv/bin/activate
python -m src.main

Check the output for email sending status.

Test 2: Check Logs

tail -n 50 data/logs/news-agent.log

Look for:

• INFO - Email sent successfully (success)
• ERROR - SMTP error sending email (failure with details)

Test 3: Verify Credentials

# Check .env file has credentials
cat .env | grep SMTP

# Should show:
# SMTP_USERNAME=your-email@domain.com
# SMTP_PASSWORD=your-password

Troubleshooting

Error: "Authentication failed"

Cause: Wrong username or password

Solutions:

1. Verify SMTP_USERNAME matches your email exactly
2. For Gmail: Use App Password, not regular password
3. Check for typos in password
4. Ensure no extra spaces in .env file

Error: "Connection refused"

Cause: Wrong host or port, or firewall blocking

Solutions:

1. Verify mail server hostname is correct
2. Check if port 587 or 465 is open:

   telnet mail.yourdomain.com 587
   

3. Check firewall rules:

   sudo firewall-cmd --list-all
   

4. Try alternative port (465 instead of 587)

Error: "Certificate verification failed"

Cause: SSL/TLS certificate issues

Solutions:

1. Ensure your mail server has valid SSL certificate
2. If using self-signed certificate, you may need to adjust Python SSL settings (not recommended for security)

Error: "Sender address rejected"

Cause: The "from" address doesn't match authenticated user

Solutions:

1. Ensure email.from in config.yaml matches SMTP_USERNAME
2. Some servers require exact match between sender and authenticated user

Error: "Timeout"

Cause: Network issues or slow mail server

Solutions:

1. Check internet connectivity
2. Try a different network
3. Verify mail server is responsive

Security Best Practices

1. Never commit .env file - It's gitignored by default
2. Use App Passwords - For Gmail and similar services
3. Use TLS/SSL - Always encrypt the connection (port 587 or 465)
4. Restrict file permissions:

   chmod 600 .env
   

5. Rotate passwords regularly - Change SMTP password periodically

Advanced: Testing SMTP Manually

You can test SMTP connection with OpenSSL:

# Test STARTTLS (port 587)
openssl s_client -starttls smtp -connect mail.yourdomain.com:587

# Test SSL (port 465)
openssl s_client -connect mail.yourdomain.com:465

# If connection succeeds, you'll see certificate info and can test SMTP commands:
EHLO localhost
AUTH LOGIN
# (enter base64 encoded username and password)

Getting Help

If you're still having issues:

1. Check mail server logs (if you control the server)
2. Contact your mail provider - They can verify SMTP settings
3. Review News Agent logs - Often contains specific error messages:

   cat data/logs/news-agent.log
   

4. Test with another SMTP tool - Verify credentials work outside News Agent

Example Working Configurations

Personal Mail Server (Most Common)

.env:

SMTP_USERNAME=myemail@mydomain.com
SMTP_PASSWORD=MySecurePassword123

config.yaml:

email:
  to: "myemail@mydomain.com"
  from: "news-agent@mydomain.com"
  smtp:
    host: "mail.mydomain.com"
    port: 587
    use_tls: true
    use_ssl: false

Gmail with App Password

.env:

SMTP_USERNAME=myemail@gmail.com
SMTP_PASSWORD=abcdabcdabcdabcd

config.yaml:

email:
  to: "myemail@gmail.com"
  from: "myemail@gmail.com"
  smtp:
    host: "smtp.gmail.com"
    port: 587
    use_tls: true
    use_ssl: false