Newsletter-Gutschein-Aktion

Mit der Newsletter-Gutschein-Aktion können Sie Abonnenten automatisch einen Gutschein per E-Mail zusenden – zum Beispiel als Anreiz für eine Newsletter-Anmeldung. Jede E-Mail-Adresse erhält den Gutschein nur einmal.

Funktionsweise

1. Ein externer Dienst (z. B. Ihr Newsletter-Tool) ruft den Endpunkt mit der E-Mail-Adresse des Abonnenten auf.
2. Das Plugin prüft, ob diese Adresse den Aktionsgutschein bereits erhalten hat.
3. Wenn nicht: Ein neuer Gutschein wird über die JTL Vouchers API erstellt, in die Datenbank eingetragen und mit PDF-Anhang per E-Mail verschickt.
4. Der Besucher sieht eine HTML-Seite mit Bestätigung oder Fehlermeldung — oder wird auf eine konfigurierte Ziel-URL weitergeleitet.

Konfiguration

Navigieren Sie zu Administration > Erweiterungen > Meine Erweiterungen > JTL Gutscheine > Konfiguration und öffnen Sie die Karte Newsletter-Gutschein-Aktion.

Einstellung	Beschreibung	Standard
Aktion aktivieren	Schaltet den Endpunkt ein/aus	Aus
Gutscheinwert (EUR)	Wert des ausgestellten Gutscheins	—
Sicherheits-Token	Optionaler Geheimschlüssel (siehe unten)	leer
Weiterleitungs-URL	Nach erfolgreicher Erstellung: Weiterleitung zu dieser URL. Leer lassen für die eingebaute Bestätigungsseite.	leer

Hinweis

Der Endpunkt ist standardmäßig deaktiviert. Aktivieren Sie ihn erst, wenn Gutscheinwert und (empfohlen) ein Sicherheits-Token konfiguriert sind.

Endpunkt

GET /voucher/aktion?mail=EMAIL[&token=TOKEN]

Parameter

Parameter	Pflicht	Beschreibung
mail	Ja	E-Mail-Adresse des Empfängers
token	Nein*	Sicherheits-Token (*Pflicht wenn in Konfiguration gesetzt)

Antworten

Der Endpunkt gibt immer eine HTML-Seite zurück (kein JSON). Der HTTP-Statuscode bleibt aussagekräftig für Ihr Newsletter-Tool — der Benutzer sieht eine lesbare Seite.

HTTP-Status	Situation	Angezeigte Seite
200	Gutschein erfolgreich erstellt	Bestätigungsseite mit Code und Wert
302	Gutschein erstellt + Weiterleitungs-URL konfiguriert	Weiterleitung zur konfigurierten URL
400	Keine oder ungültige E-Mail-Adresse	Fehlerseite
403	Token fehlt oder stimmt nicht überein	Fehlerseite "Zugriff verweigert"
409	Diese E-Mail hat den Gutschein bereits erhalten	Fehlerseite "Gutschein bereits ausgestellt"
503	Aktion deaktiviert oder Gutscheinwert nicht konfiguriert	Fehlerseite
500	Interner Fehler	Allgemeine Fehlerseite

Weiterleitung (Weiterleitungs-URL)

Wenn Sie die Besucher nach der Gutscheinerstellung zu einer eigenen Seite schicken möchten (z. B. einer Erlebnis-Welt-Seite oder einer externen Danke-Seite), tragen Sie die Ziel-URL in das Feld Weiterleitungs-URL ein.

Beispiele:

• Interne Erlebnis-Welt: /erlebnisse/gutschein-bestaetigung
• Externe Seite: https://www.ihr-shop.de/newsletter-danke
• Absolut mit Domain: https://ihr-shop.de/danke

Ist das Feld leer, zeigt das Plugin nach erfolgreicher Erstellung automatisch eine eingebaute Bestätigungsseite mit Gutscheincode und Wert an — kein weiterer Konfigurationsaufwand.

Sicherheits-Token

Ohne Token ist der Endpunkt öffentlich erreichbar — jeder könnte beliebig viele Gutscheine ausstellen (zwar je nur einen pro Adresse, aber mit beliebig vielen Adressen).

Empfehlung: Tragen Sie einen zufälligen, langen Token in die Konfiguration ein und übergeben Sie ihn nur Ihrem Newsletter-Dienst.

/voucher/aktion?mail=newsletter@beispiel.de&token=mein-geheimer-schluessel

Der Vergleich erfolgt mit hash_equals() (Timing-sicher).

Integration mit Newsletter-Tools

Beispiel: Webhook-URL in Mailchimp / Brevo

Tragen Sie als Webhook-URL bei erfolgreicher Anmeldung ein:

https://ihr-shop.de/voucher/aktion?mail={{contact.email}}&token=IHR_TOKEN

Ersetzen Sie {{contact.email}} durch den jeweiligen Platzhalter Ihres Tools.

Beispiel: curl (Test)

curl -v "https://ihr-shop.de/voucher/aktion?mail=test@beispiel.de&token=IHR_TOKEN"

Der HTTP-Statuscode zeigt Erfolg (200/302) oder Fehler (4xx/5xx) — für Webhook-Monitoring ausreichend.

E-Mail-Vorlage

Die versandte E-Mail verwendet die im Plugin konfigurierte Gutschein-E-Mail-Vorlage (i7_jtl_voucher_code_delivery). In der Vorlage stehen folgende Variablen zur Verfügung:

Variable	Inhalt
voucherCode	Der generierte Gutscheincode
voucherAmount	Der Gutscheinwert in EUR

Die E-Mail enthält den Gutschein außerdem als PDF-Anhang (sofern die PDF-Generierung konfiguriert ist). Schlägt die PDF-Erstellung fehl, wird die E-Mail ohne Anhang zugestellt.

Duplikatschutz

Jede E-Mail-Adresse wird nach dem ersten erfolgreichen Versand in der Tabelle i7_newsletter_voucher_log eingetragen. Weitere Anfragen mit derselben Adresse geben HTTP 409 zurück und erstellen keinen neuen Gutschein. Die Eindeutigkeit ist zusätzlich durch einen UNIQUE KEY auf der Spalte email auf Datenbankebene abgesichert.