Newsletter

1. Wofuer ist diese Funktion

Die Newsletter-Seite ermoeglicht den Versand von E-Mail-Broadcasts an ausgewaehlte Empfaengergruppen. Sie verbindet Octoserv-eigene Entwurfsverwaltung mit der Groundhogg-Broadcast-Engine und bietet eine vollstaendige Steuerung des Newsletter-Lebenszyklus: vom Erstellen eines Entwurfs ueber die Segmentierung der Empfaenger bis zur Aktivierung, Planung und Deaktivierung.

Die Seite ist ueber den Navigationspunkt "Newsletter" in der Sidebar erreichbar (/octo/newsletter). Sie besteht aus zwei Hauptbereichen: einem Einstellungsbereich zum Konfigurieren neuer Newsletter (oben) und einer Uebersichtsliste aller bestehenden Newsletter und Entwuerfe (unten).

Im Unterschied zur E-Mail-Seite, die sich auf das Erstellen und Verwalten von E-Mail-Vorlagen konzentriert, dreht sich die Newsletter-Seite um den tatsaechlichen Versand: Welche Vorlage wird an welche Empfaenger zu welchem Zeitpunkt gesendet? Die Newsletter-Seite nutzt die auf der E-Mail-Seite erstellten Vorlagen als Basis fuer Broadcasts.

2. Ziel und Vorteil

• Entwurfssystem: Newsletter koennen als Entwuerfe gespeichert werden, bevor sie aktiviert werden. Das erlaubt eine sorgfaeltige Vorbereitung und Pruefung vor dem Versand.
• Tag-basierte Segmentierung: Empfaenger werden ueber Groundhogg-Tags ausgewaehlt. Tags koennen einbezogen oder ausgeschlossen werden, sodass praezise Zielgruppen definiert werden koennen.
• Flexible Planung: Newsletter koennen entweder sofort gesendet oder fuer einen bestimmten Zeitpunkt geplant werden. Optional kann der Versand in der lokalen Zeitzone des Empfaengers erfolgen.
• Newslettertemplates: Haeufig verwendete Tag-Kombinationen und Einstellungen koennen als wiederverwendbare Templates (Segmente) gespeichert werden, um die Erstellung wiederkehrender Newsletter zu beschleunigen.
• Lebenszyklussteuerung: Aktive Newsletter koennen deaktiviert und zurueck in den Entwurfsstatus versetzt werden. Entwuerfe koennen jederzeit bearbeitet und erneut aktiviert werden.
• Empfaenger-Vorschau: Vor dem Versand kann die Anzahl der Empfaenger geprueft werden, um sicherzustellen, dass die Tag-Selektion die gewuenschte Zielgruppe trifft.
• E-Mail-Vorschau: Der Inhalt einer E-Mail-Vorlage kann in einer formatierten Vorschau mit Absender und Betreff betrachtet werden, ohne die E-Mail senden zu muessen.

3. Detaillierte Funktionsbeschreibung

3.1 Seitenlayout

Die Newsletter-Seite ist in zwei vertikale Bereiche unterteilt:

Oberer Bereich -- Einstellungen:

Ein dreispaltiges Raster (responsiv, mindestens 300px pro Spalte) mit allen Konfigurationsoptionen fuer einen neuen oder zu bearbeitenden Newsletter.

Unterer Bereich -- Newsletter-Uebersicht:

Eine Liste aller bestehenden Newsletter (Broadcasts und Entwuerfe) mit Statusanzeige und Aktionsbuttons.

3.2 Einstellungsbereich im Detail

E-Mail-Vorlage (Pflichtfeld)

Ein gestyltes Dropdown-Menue, das alle verfuegbaren Groundhogg-E-Mails mit Status "ready" oder "draft" anzeigt. Die E-Mails werden ueber die Groundhogg REST API (v4) geladen. Nur E-Mails mit numerischen IDs werden angezeigt (Remote-Templates von Groundhogg werden herausgefiltert).

Wenn die Seite mit dem URL-Parameter ?email=ID aufgerufen wird, wird die entsprechende E-Mail automatisch vorausgewaehlt. Dies ermoeglicht eine direkte Verknuepfung von der E-Mail-Seite zum Newsletter-Versand.

Newslettertemplate waehlen

Ein Dropdown-Menue, das gespeicherte Segmente (Newslettertemplates) laedt. Beim Auswaehlen eines Segments werden alle zugehoerigen Einstellungen (Tags, E-Mail-Vorlage, Zeitplanung) automatisch in das Formular uebernommen.

Tags einbeziehen / Tags ausschliessen

Zwei Multi-Select-Dropdowns, die alle verfuegbaren Groundhogg-Tags anzeigen. Tags werden ueber die Groundhogg REST API geladen.

Logik:

• Tags einbeziehen: Kontakte, die mindestens eines der ausgewaehlten Tags haben, werden als Empfaenger aufgenommen (ODER-Verknuepfung).
• Tags ausschliessen: Kontakte, die mindestens eines der ausgewaehlten Tags haben, werden von den Empfaengern ausgeschlossen.
• Die Kombination beider Felder ermoeglicht eine praezise Segmentierung: z.B. "Alle Kontakte mit Tag 'Kunde' OHNE Tag 'Abgemeldet'".

Datum und Uhrzeit

Datums- und Uhrzeitfelder fuer den geplanten Versandzeitpunkt. Die Standarduhrzeit ist 09:00. Beide Felder werden automatisch deaktiviert, wenn "Sofort senden" aktiviert ist.

Sofort senden

Ein Toggle-Schalter. Wenn aktiviert, werden Datum und Uhrzeit ignoriert und der Newsletter wird beim Aktivieren sofort versendet.

In lokaler Zeit senden

Ein Toggle-Schalter. Wenn aktiviert, wird die E-Mail in der lokalen Zeitzone des jeweiligen Empfaengers zugestellt (sofern diese Information in Groundhogg hinterlegt ist).

Newsletter-Titel (Pflichtfeld)

Ein Freitextfeld fuer den internen Titel des Newsletters (z.B. "Oktober-Kampagne 2025"). Dieser Titel wird in der Newsletter-Uebersicht angezeigt und dient der internen Identifikation -- er ist nicht identisch mit dem E-Mail-Betreff.

3.3 Newsletter-Aktionen

Newsletter speichern (Entwurf)

Der Button "Newsletter speichern" erstellt einen neuen Entwurf in der Octoserv-eigenen Tabelle wp_octo_news_drafts. Der Entwurf enthaelt alle Konfigurationsdaten (Vorlage, Tags, Zeitplanung, Titel) und kann spaeter bearbeitet oder aktiviert werden.

Validierung vor dem Speichern:

• E-Mail-Vorlage muss ausgewaehlt sein.
• Newsletter-Titel darf nicht leer sein.
• Entweder "Sofort senden" muss aktiviert oder Datum und Uhrzeit muessen gesetzt sein.
• Der Titel darf nicht bereits als Entwurf existieren (Duplikatpruefung).

Aenderungen speichern (Aktualisierung)

Der Button "Aenderungen speichern" erscheint, wenn ein bestehender Newsletter zum Bearbeiten geoeffnet wurde. Er aktualisiert den bestehenden Entwurf oder erstellt einen neuen Broadcast, der den alten ersetzt.

Bei Entwuerfen: Die Daten werden direkt in der Datenbank aktualisiert.

Bei aktiven Broadcasts: Der alte Broadcast wird ueber die Groundhogg REST API geloescht, ein neuer Broadcast wird mit den aktualisierten Daten erstellt, und der neue Broadcast wird automatisch geplant.

3.4 Newsletter-Uebersicht

Die Uebersichtsliste zeigt alle Newsletter in chronologischer Reihenfolge (neueste zuerst). Die Liste kombiniert Groundhogg-Broadcasts mit Octoserv-Entwuerfen.

Statusanzeige

Jeder Newsletter hat einen farbigen Statuspunkt:

Aktionsbuttons pro Newsletter

3.5 Newslettertemplate-Verwaltung

Im Einstellungsbereich (Spalte 3) befindet sich ein separater Abschnitt zur Verwaltung von Newslettertemplates.

Speichern: Ueber ein Namensfeld und den "Speichern"-Button werden die aktuell gewaehlten Einstellungen (Tags, E-Mail-Vorlage, Zeitplanung) als wiederverwendbares Template gespeichert. Duplikate werden abgelehnt.

Laden: Beim Auswaehlen eines Segments im Dropdown "Newslettertemplate waehlen" werden alle gespeicherten Werte automatisch in das Formular uebernommen.

Loeschen: Ueber den "Loeschen"-Button wird das aktuell ausgewaehlte Segment entfernt.

3.6 Drei-Schichten-Architektur

Das Newsletter-System verwendet eine dreischichtige Architektur:

UI-Schicht (JavaScript):

• Formularverwaltung und Benutzerinteraktion.
• Direkter Zugriff auf die Groundhogg REST API fuer Broadcasts (Erstellen, Planen, Loeschen).
• AJAX-Aufrufe an die PHP-Anwendungsschicht fuer Entwuerfe und Metadaten.

Anwendungsschicht (PHP/AJAX):

• Geschaeftslogik und Datenvalidierung.
• Entwurfsverwaltung (CRUD-Operationen auf wp_octo_news_drafts).
• Broadcast-Metadaten (Titel, Tags) in wp_octo_news_broadcasts.
• Segmentverwaltung in wp_octo_news_segments.
• Empfaengerberechnung ueber die Groundhogg Contact Query.
• Aktivierung/Deaktivierung mit Konvertierung zwischen Datenformaten.

Datenschicht:

Drei eigene Octoserv-Tabellen plus die Groundhogg-Broadcast-Tabelle:

3.7 Entwurfs-Lebenszyklus

Ein Newsletter durchlaeuft folgende Zustaende:

Erstellen --> Entwurf --> Aktivieren --> Geplant/Ausstehend --> Gesendet

Vom Status "Geplant/Ausstehend" kann durch Deaktivieren zurueck in den Status "Entwurf" gewechselt werden.

Erstellen: Der Benutzer konfiguriert den Newsletter und klickt "Newsletter speichern". Ein Entwurf wird in wp_octo_news_drafts gespeichert.

Aktivieren: Der Benutzer klickt den Aktivieren-Button. Der PHP-Handler liest den Entwurf, konvertiert die Tags vom JSON-Format in das Groundhogg-Filter-Format (serialisiertes PHP), berechnet den Versandzeitpunkt unter Beruecksichtigung der WordPress-Zeitzone, schreibt direkt in die wp_gh_broadcasts-Tabelle, kopiert die Metadaten nach wp_octo_news_broadcasts und loescht den Entwurf. Anschliessend wird der Broadcast ueber den Groundhogg-Scheduling-Endpoint geplant.

Deaktivieren: Der Benutzer klickt den Deaktivieren-Button. Die Metadaten werden aus wp_octo_news_broadcasts gelesen, ein neuer Entwurf wird in wp_octo_news_drafts erstellt, und der Groundhogg-Broadcast wird geloescht.

3.8 Empfaengerberechnung

Die Empfaengeranzahl wird serverseitig berechnet (AJAX-Action: octo_list_news_recipients).

Ablauf:

1. Die einbezogenen und ausgeschlossenen Tags werden an den Server gesendet.
2. Der Server erstellt eine Groundhogg Contact Query mit:
   • optin_status = 2 (nur bestaetigte Kontakte).
   • tags_include fuer einbezogene Tags (ODER-Verknuepfung).
   • tags_exclude fuer ausgeschlossene Tags.
3. Die Anzahl der passenden Kontakte wird zurueckgegeben.

Die Empfaenger-Uebersicht zeigt in einem dreispaltigen Layout:

• Spalte 1: Gesamtanzahl der ausgewaehlten Empfaenger.
• Spalte 2: Liste der einbezogenen Tags (gruen) und ausgeschlossenen Tags (rot).
• Spalte 3: Liste aller verfuegbaren Tags, die noch nicht verwendet wurden.

4. Benutzerdokumentation / Anwendung

4.1 Newsletter-Seite aufrufen

1. In der Sidebar auf "Newsletter" klicken.
2. Die Seite zeigt oben das Einstellungsformular und unten die Newsletter-Uebersicht.

4.2 Neuen Newsletter als Entwurf speichern

1. Im Dropdown "E-Mail Vorlage" die gewuenschte E-Mail-Vorlage auswaehlen.
2. Unter "Tags einbeziehen" die Zielgruppen-Tags waehlen (z.B. "Kunde", "Berlin").
3. Optional unter "Tags ausschliessen" Tags waehlen, die ausgeschlossen werden sollen (z.B. "Abgemeldet").
4. Datum und Uhrzeit fuer den geplanten Versand festlegen -- oder "Sofort senden" aktivieren.
5. Einen aussagekraeftigen Newsletter-Titel eingeben (z.B. "Oktober-Newsletter 2025").
6. Auf "Newsletter speichern" klicken.
7. Der Entwurf erscheint in der Uebersicht mit gelbem Statuspunkt.

4.3 Entwurf bearbeiten

1. In der Newsletter-Uebersicht den Zahnrad-Button des gewuenschten Entwurfs klicken.
2. Das Formular oben wird mit den gespeicherten Daten befuellt.
3. Aenderungen vornehmen (z.B. andere Tags waehlen oder Datum aendern).
4. Auf "Aenderungen speichern" klicken.

4.4 Newsletter aktivieren (versenden)

1. In der Newsletter-Uebersicht den gruenen Haekchen-Button des Entwurfs klicken.
2. Der Entwurf wird in einen aktiven Broadcast konvertiert.
3. Die Statusmeldung "Newsletter wurde aktiviert und geplant" bestaetigt den Erfolg.
4. Der Newsletter erscheint nun mit gruenem Statuspunkt und dem Status "Geplant" oder "Ausstehend".

4.5 Aktiven Newsletter deaktivieren

1. In der Newsletter-Uebersicht den roten X-Button des aktiven Newsletters klicken.
2. Der Broadcast wird zurueck in einen Entwurf konvertiert.
3. Die Statusmeldung "Deaktiviert und als Entwurf gespeichert" bestaetigt den Vorgang.
4. Der Newsletter erscheint wieder mit gelbem Statuspunkt als Entwurf.

4.6 E-Mail-Vorlage bearbeiten

1. In der Newsletter-Uebersicht den Stift-Button klicken.
2. Der Groundhogg-E-Mail-Editor oeffnet sich im iFrame-Modal.
3. Aenderungen am Inhalt oder Design der E-Mail vornehmen.
4. Im Editor speichern und das Modal schliessen.

4.7 E-Mail-Vorschau anzeigen

1. In der Newsletter-Uebersicht den Augen-Button klicken.
2. Eine formatierte Vorschau zeigt den Absender (Name, E-Mail, Avatar) und den Betreff.
3. Darunter wird der vollstaendige E-Mail-Inhalt in einem eingebetteten Frame dargestellt.

4.8 Empfaenger pruefen

1. In der Newsletter-Uebersicht den Personen-Button klicken.
2. Eine Uebersicht zeigt:
   • Die Gesamtanzahl der Empfaenger (grosse Zahl).
   • Die einbezogenen Tags (gruen hervorgehoben).
   • Die ausgeschlossenen Tags (rot hervorgehoben).
   • Alle verfuegbaren Tags, die nicht verwendet werden.

4.9 Newslettertemplate speichern und verwenden

Template speichern:

1. Die gewuenschten Einstellungen im Formular konfigurieren (Tags, E-Mail-Vorlage, Zeitplanung).
2. Im Bereich "Newslettertemplate verwalten" einen Templatenamen eingeben (z.B. "Kunden + Berlin").
3. Auf "Speichern" klicken.

Template laden:

1. Im Dropdown "Newslettertemplate waehlen" das gewuenschte Template auswaehlen.
2. Alle gespeicherten Einstellungen werden automatisch in das Formular uebernommen.
3. Optional Anpassungen vornehmen.
4. Den Newsletter speichern oder direkt aktivieren.

Template loeschen:

1. Das gewuenschte Template im Dropdown auswaehlen.
2. Auf "Loeschen" klicken.

4.10 Newsletter loeschen

1. In der Newsletter-Uebersicht den Papierkorb-Button klicken.
2. Bei Entwuerfen wird der Entwurf aus der Octoserv-Tabelle entfernt.
3. Bei Broadcasts wird sowohl der Groundhogg-Broadcast als auch die Octoserv-Metadaten geloescht.

5. Anwendungsbeispiele

Beispiel 1: Monatlicher Kunden-Newsletter

Ein Unternehmen moechte jeden Monat einen Newsletter an alle bestaetigten Kunden senden.

Vorgehen:

1. Auf der E-Mail-Seite eine E-Mail-Vorlage "Monatlicher Newsletter" erstellen und gestalten.
2. Auf der Newsletter-Seite die E-Mail-Vorlage im Dropdown auswaehlen.
3. Unter "Tags einbeziehen" den Tag "Kunde" waehlen.
4. Unter "Tags ausschliessen" den Tag "Newsletter-Abgemeldet" waehlen.
5. Datum auf den gewuenschten Versandtag setzen, Uhrzeit auf 09:00.
6. Den Titel "Monatlicher Newsletter Februar 2026" eingeben.
7. Auf "Newsletter speichern" klicken, um den Entwurf zu sichern.
8. Den Empfaenger-Button klicken, um die Anzahl der Empfaenger zu pruefen.
9. Wenn alles stimmt, den Aktivieren-Button klicken.

Zeitsparend fuer den Folgemonat:

1. Ein Newslettertemplate "Monatlicher Kunden-Newsletter" speichern.
2. Im naechsten Monat das Template laden, die E-Mail-Vorlage und den Titel anpassen, und direkt speichern.

Beispiel 2: Regionale Veranstaltungseinladung

Ein Unternehmen moechte eine Veranstaltungseinladung nur an Kontakte in bestimmten Regionen senden.

Vorgehen:

1. Auf der E-Mail-Seite eine Einladungs-E-Mail erstellen.
2. Auf der Newsletter-Seite die Einladungs-E-Mail auswaehlen.
3. Unter "Tags einbeziehen" die regionalen Tags waehlen: "Region Nord", "Region Ost".
4. Unter "Tags ausschliessen" den Tag "Event-Abgemeldet" waehlen.
5. "In lokaler Zeit senden" aktivieren, damit die Einladung morgens in der Zeitzone des Empfaengers ankommt.
6. Den Newsletter speichern, die Empfaenger-Vorschau pruefen und bei korrekter Auswahl aktivieren.

Beispiel 3: Zeitkritischer Newsletter mit sofortigem Versand

Ein wichtiges Update muss sofort an alle Kontakte gesendet werden.

Vorgehen:

1. Auf der E-Mail-Seite eine dringende Mitteilung erstellen (oder eine bestehende Vorlage anpassen).
2. Auf der Newsletter-Seite die Vorlage auswaehlen.
3. Tags nach Bedarf setzen (oder keine Tags waehlen, um alle Kontakte zu erreichen).
4. "Sofort senden" aktivieren -- Datum und Uhrzeit werden automatisch deaktiviert.
5. Einen Titel eingeben und "Newsletter speichern" klicken.
6. Sofort den Aktivieren-Button klicken.
7. Der Newsletter wird unverzueglich versendet und der Fortschritt wird in der Statusleiste angezeigt.