📧 Jellyfin Newsletter

Automatisches Newsletter-System für Jellyfin, das regelmäßig über neue Medien in deiner Bibliothek informiert.

✨ Features

Kernfunktionen

• 📚 Bibliotheksauswahl: Wähle welche Bibliotheken überwacht werden
• ⏰ Automatischer Versand: Täglich, wöchentlich oder monatlich
• 👥 Empfängerverwaltung: Mehrere Empfänger mit Opt-in/Opt-out
• 🎨 HTML Templates: Schöne Email-Vorlagen mit Postern und Metadaten
• 🔧 Web-Interface: Einfache Konfiguration über NiceGUI

Erweiterte Features

• Zeitplanung: Flexibler Zeitplan (täglich/wöchentlich/monatlich)
• Zeitfenster: Nur neue Medien der letzten X Tage
• Gruppierung: Nach Bibliothek, Genre oder Datum
• Filter: Ausschluss bestimmter Genres/Tags
• Sortierung: Nach Datum, Rating oder alphabetisch
• Mindestanzahl: Nur versenden wenn X neue Items vorhanden
• Vorschau: Newsletter vor Versand testen
• Deep Links: Direktlinks zu Medien in Jellyfin

🚀 Installation

Voraussetzungen

• Docker & Docker Compose
• Jellyfin Server mit API Zugriff
• SMTP Server (Gmail, SendGrid, etc.)

Docker Compose (empfohlen)

1. Repository klonen oder Dateien kopieren

git clone <repo-url> jellyfin-newsletter
cd jellyfin-newsletter

2. Konfiguration erstellen

cp config.yaml.example config.yaml

3. Container starten

docker-compose up -d

4. Web-Interface öffnen

http://localhost:8080

Manuelle Installation

1. Dependencies installieren

pip install -r requirements.txt

2. Konfiguration erstellen

cp config.yaml.example config.yaml

3. Anwendung starten

python app.py

⚙️ Konfiguration

Jellyfin API Key erstellen

1. Öffne Jellyfin Dashboard
2. Gehe zu Dashboard → API Keys
3. Klicke auf + um neuen Key zu erstellen
4. Gib einen Namen ein (z.B. "Newsletter")
5. Kopiere den API Key

Gmail SMTP Setup

Für Gmail benötigst du ein App-Passwort:

1. Gehe zu Google Account Settings
2. Sicherheit → 2-Faktor-Authentifizierung aktivieren
3. App-Passwörter erstellen
4. Wähle "Mail" und "Anderes Gerät"
5. Kopiere das generierte Passwort

config.yaml:

smtp:
  host: "smtp.gmail.com"
  port: 587
  username: "deine-email@gmail.com"
  password: "xxxx xxxx xxxx xxxx"  # App-Passwort
  from_email: "deine-email@gmail.com"
  from_name: "Jellyfin Newsletter"

Andere SMTP Provider

SendGrid:

smtp:
  host: "smtp.sendgrid.net"
  port: 587
  username: "apikey"
  password: "YOUR_SENDGRID_API_KEY"

Mailgun:

smtp:
  host: "smtp.mailgun.org"
  port: 587
  username: "postmaster@your-domain.mailgun.org"
  password: "YOUR_MAILGUN_PASSWORD"

Eigener Mailserver:

smtp:
  host: "mail.example.com"
  port: 587  # oder 465 für SSL
  username: "newsletter@example.com"
  password: "YOUR_PASSWORD"

📖 Nutzung

Web-Interface

Das Admin-Interface ist unter http://localhost:8080 erreichbar und bietet folgende Tabs:

1. Jellyfin

• Server URL und API Key konfigurieren
• Verbindung testen
• Bibliotheken auswählen

2. Newsletter

• Minimale Anzahl neuer Items
• Tage zurückblicken
• Gruppierung (Bibliothek/Genre/Datum)
• Sortierung (Datum/Rating/Alphabetisch)
• Poster und Metadaten aktivieren

3. SMTP

• SMTP Server Einstellungen
• Absender konfigurieren

4. Empfänger

• Email-Adressen hinzufügen/entfernen
• Empfängerliste verwalten

5. Template

• Header/Footer Text
• Beschreibung aktivieren
• Beschreibungslänge

6. Zeitplan

• Zeitplan wählen (täglich/wöchentlich/monatlich)
• Wochentag/Tag im Monat
• Uhrzeit festlegen

7. Test & Vorschau

• Test-Newsletter an beliebige Email senden
• Vorschau im Browser anzeigen
• Manueller Versand an alle Empfänger

Zeitplan-Beispiele

Jeden Montag um 9:00 Uhr:

schedule: "weekly"
schedule_day: 0  # 0=Montag
schedule_time: "09:00"

Täglich um 18:00 Uhr:

schedule: "daily"
schedule_time: "18:00"

Jeden 1. des Monats um 10:00 Uhr:

schedule: "monthly"
schedule_day: 1
schedule_time: "10:00"

Filter-Beispiele

Dokumentationen ausschließen:

excluded_genres:
  - "Documentary"
  - "News"

Kinderinhalte ausschließen:

excluded_tags:
  - "Kids"
  - "Children"

🎨 Template Anpassung

Die HTML-Templates befinden sich in templates/newsletter.html und können vollständig angepasst werden.

Custom Template erstellen

1. Erstelle templates/ Ordner falls nicht vorhanden
2. Kopiere das Default-Template aus newsletter.py
3. Passe HTML/CSS nach Belieben an
4. Template verwendet Jinja2 Syntax

Verfügbare Template-Variablen:

• header_text - Header Text
• footer_text - Footer Text
• groups - Liste der gruppierten Items
• config - Gesamte Konfiguration
• jellyfin_url - Jellyfin Server URL
• current_date - Aktuelles Datum
• total_items - Anzahl neuer Items

🔧 Erweiterte Konfiguration

Proxmox Integration

In docker-compose.yml:

services:
  jellyfin-newsletter:
    # ...
    extra_hosts:
      - "jellyfin:192.168.1.100"  # Jellyfin Server IP

Hinter Reverse Proxy (Pangolin)

services:
  jellyfin-newsletter:
    # ...
    networks:
      - proxy
      - default

networks:
  proxy:
    external: true
    name: pangolin_default

Umgebungsvariablen

Alternativ zur config.yaml können auch Environment Variables genutzt werden:

environment:
  - JELLYFIN_URL=http://jellyfin:8096
  - JELLYFIN_API_KEY=your_key
  - SMTP_HOST=smtp.gmail.com
  - SMTP_PORT=587
  - SMTP_USERNAME=your@email.com
  - SMTP_PASSWORD=your_password

🐛 Troubleshooting

Newsletter wird nicht versendet

1. Logs prüfen:

docker-compose logs -f jellyfin-newsletter

2. Verbindung testen:

   • Web-Interface → Jellyfin Tab → "Verbindung testen"
   • Prüfe API Key und URL

3. SMTP testen:

   • Test & Vorschau Tab → Test Newsletter versenden
   • Prüfe SMTP Credentials

Keine neuen Items im Newsletter

• Prüfe days_lookback Einstellung
• Prüfe ob Bibliotheken korrekt ausgewählt sind
• Prüfe min_items Einstellung
• Prüfe Filter (excluded_genres, excluded_tags)

Poster werden nicht angezeigt

• Prüfe ob Jellyfin Server von außen erreichbar ist
• Eventuell Reverse Proxy Konfiguration prüfen
• include_posters: false setzen wenn Probleme bestehen

SMTP Authentifizierung fehlschlägt

Gmail:

• App-Passwort verwenden (nicht reguläres Passwort)
• 2FA muss aktiviert sein

Andere Provider:

• Prüfe ob Port korrekt ist (587 für TLS, 465 für SSL)
• Prüfe ob less secure apps aktiviert ist (falls erforderlich)

📊 Monitoring

Logs

# Docker Logs live verfolgen
docker-compose logs -f

# Nur Newsletter logs
docker-compose logs -f | grep newsletter

Scheduler Status

Der Scheduler läuft im Hintergrund und loggt:

• Nächster geplanter Versand
• Versanderfolge
• Fehler

🔒 Sicherheit

Best Practices

1. API Key Schutz:

   • Nutze Read-Only API Keys wenn möglich
   • Sichere config.yaml mit passenden Berechtigungen

2. SMTP Credentials:

   • Nutze App-Passwörter statt Hauptpasswort
   • Erwäge Secrets Management (Docker Secrets, etc.)

3. Network Security:

   • Binde Web-Interface nur an localhost wenn möglich
   • Nutze HTTPS über Reverse Proxy

Docker Secrets (optional)

services:
  jellyfin-newsletter:
    secrets:
      - jellyfin_api_key
      - smtp_password

secrets:
  jellyfin_api_key:
    file: ./secrets/jellyfin_api_key.txt
  smtp_password:
    file: ./secrets/smtp_password.txt

🔄 Updates

Docker

# Container stoppen
docker-compose down

# Neue Version pullen/builden
git pull
docker-compose build

# Container starten
docker-compose up -d

Backup

Sichere diese Dateien:

• config.yaml
• data/ (falls vorhanden)

📝 Lizenz

MIT License - nutze und modifiziere nach Belieben!

🤝 Beitragen

Pull Requests sind willkommen! Für größere Änderungen bitte zuerst ein Issue öffnen.

💡 Ideen für Erweiterungen

• Opt-out Links in Emails
• "Auf Watchlist" Button im Newsletter
• Multi-Language Support
• Statistiken Dashboard
• Webhook Support für Discord/Slack
• Custom CSS Upload im Web-Interface
• Email Template Gallery

📞 Support

Bei Fragen oder Problemen:

1. Prüfe die Logs
2. Schau in die Troubleshooting Sektion
3. Erstelle ein GitHub Issue

---

Viel Spaß mit deinem automatischen Jellyfin Newsletter! 🎬📧