# 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

```bash
nano .env
```

Add your SMTP credentials:
```env
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`

```bash
nano config.yaml
```

Update the SMTP section under `email`:
```yaml
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.):

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

```env
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"

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

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

### Outlook / Office 365

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

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

### SendGrid

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

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

### Mailgun

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

```env
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

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

Check the output for email sending status.

### Test 2: Check Logs

```bash
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

```bash
# 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:
   ```bash
   telnet mail.yourdomain.com 587
   ```
3. Check firewall rules:
   ```bash
   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**:
   ```bash
   chmod 600 .env
   ```
5. **Rotate passwords regularly** - Change SMTP password periodically

## Advanced: Testing SMTP Manually

You can test SMTP connection with OpenSSL:

```bash
# 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:
   ```bash
   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:**
```env
SMTP_USERNAME=myemail@mydomain.com
SMTP_PASSWORD=MySecurePassword123
```

**config.yaml:**
```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:**
```env
SMTP_USERNAME=myemail@gmail.com
SMTP_PASSWORD=abcdabcdabcdabcd
```

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