From 07af49202658a730af4dad392d06014fdf0b3b90 Mon Sep 17 00:00:00 2001
From: ilia <ilia@levkin.ca>
Date: Mon, 15 Dec 2025 15:43:44 -0500
Subject: [PATCH] Add email setup guide for levkin.ca mail server

Configuration for test@levkin.ca:
- SMTP: mail.levkin.ca:587 (STARTTLS)
- Includes setup instructions
- Testing checklist
- Troubleshooting guide

Note: .env file created locally (not committed, in .gitignore)
---
 EMAIL_SETUP.md | 143 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)
 create mode 100644 EMAIL_SETUP.md

diff --git a/EMAIL_SETUP.md b/EMAIL_SETUP.md
new file mode 100644
index 0000000..653d9fc
--- /dev/null
+++ b/EMAIL_SETUP.md
@@ -0,0 +1,143 @@
+# Email Setup for levkin.ca
+
+Your POTE system is configured to use `test@levkin.ca` for sending reports.
+
+## ✅ Configuration Done
+
+The `.env` file has been created with these settings:
+
+```env
+SMTP_HOST=mail.levkin.ca
+SMTP_PORT=587
+SMTP_USER=test@levkin.ca
+SMTP_PASSWORD=YOUR_MAILBOX_PASSWORD_HERE
+FROM_EMAIL=test@levkin.ca
+REPORT_RECIPIENTS=test@levkin.ca
+```
+
+## 🔑 Next Steps
+
+### 1. Add Your Password
+
+Edit `.env` and replace `YOUR_MAILBOX_PASSWORD_HERE` with your actual mailbox password:
+
+```bash
+nano .env
+# Find the line: SMTP_PASSWORD=YOUR_MAILBOX_PASSWORD_HERE
+# Replace with: SMTP_PASSWORD=your_actual_password
+# Save and exit (Ctrl+X, Y, Enter)
+```
+
+### 2. Test the Connection
+
+```bash
+source venv/bin/activate
+python scripts/send_daily_report.py --to test@levkin.ca --test-smtp
+```
+
+If successful, you'll see:
+```
+SMTP connection test successful!
+✓ Daily report sent successfully!
+```
+
+And you should receive a test email at `test@levkin.ca`!
+
+### 3. Set Up Automation
+
+Once email is working, set up automated reports:
+
+```bash
+./scripts/setup_cron.sh
+```
+
+This will:
+- Use `test@levkin.ca` for sending
+- Send reports to `test@levkin.ca` (or you can specify different recipients)
+- Schedule daily reports (default: 6 AM)
+- Schedule weekly reports (Sundays at 8 AM)
+
+## 📧 Email Server Details (For Reference)
+
+Based on your Thunderbird setup:
+
+**Outgoing SMTP (what POTE uses):**
+- Host: `mail.levkin.ca`
+- Port: `587`
+- Security: `STARTTLS` (TLS on port 587)
+- Authentication: Normal password
+- Username: `test@levkin.ca`
+
+**Incoming IMAP (for reading emails in Thunderbird):**
+- Host: `mail.levkin.ca`
+- Port: `993`
+- Security: `SSL/TLS`
+- Username: `test@levkin.ca`
+
+POTE only uses **SMTP (outgoing)** to send reports.
+
+## 🔒 Security Notes
+
+1. **Never commit `.env` to git!**
+   - Already in `.gitignore` ✅
+   - Contains sensitive password
+
+2. **Password Security:**
+   - The password in `.env` is the same one you use in Thunderbird
+   - It's stored in plain text locally (secure file permissions recommended)
+   - Consider using application-specific passwords if your mail server supports them
+
+3. **File Permissions (On Proxmox):**
+   ```bash
+   chmod 600 .env  # Only owner can read/write
+   ```
+
+## 🎯 Change Recipients
+
+To send reports to different email addresses (not just test@levkin.ca):
+
+**Option 1: Edit .env**
+```env
+REPORT_RECIPIENTS=user1@example.com,user2@example.com,test@levkin.ca
+```
+
+**Option 2: Override in cron/scripts**
+```bash
+# Manual send to different recipient
+python scripts/send_daily_report.py --to someone-else@example.com
+
+# The FROM address will still be test@levkin.ca
+```
+
+## ✅ Testing Checklist
+
+- [ ] Updated `.env` with your actual password
+- [ ] Run `python scripts/send_daily_report.py --to test@levkin.ca --test-smtp`
+- [ ] Checked inbox at test@levkin.ca (check spam folder!)
+- [ ] If successful, run `./scripts/setup_cron.sh` to automate
+
+## 🐛 Troubleshooting
+
+### Error: "SMTP connection failed"
+
+Check:
+1. Password is correct in `.env`
+2. Port 587 is not blocked by firewall
+3. Mail server is accessible: `telnet mail.levkin.ca 587`
+
+### Email not received
+
+1. Check spam folder in test@levkin.ca
+2. Check Thunderbird or webmail for the message
+3. Check POTE logs: `tail -f ~/logs/daily_run.log`
+
+### "Authentication failed"
+
+- Double-check username is `test@levkin.ca` (not just `test`)
+- Verify password is correct
+- Ensure account is active in mailcow
+
+---
+
+**You're all set! POTE will send reports from test@levkin.ca 📧**
+