322 lines
6.6 KiB
Markdown
322 lines
6.6 KiB
Markdown
# 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
|
|
```
|