first commit
This commit is contained in:
321
SMTP_CONFIG.md
Normal file
321
SMTP_CONFIG.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user