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 Vouchers Schnittstelle > 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"
429	Zu viele Anfragen von derselben IP (Rate-Limit)	Fehlerseite "Zu viele Anfragen" (mit Retry-After-Header)
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), tragen Sie die Ziel-URL in das Feld Weiterleitungs-URL ein.

Nur same-origin Ziele sind erlaubt (Schutz gegen Open-Redirect): ein relativer Pfad oder eine absolute http(s)-URL auf derselben Domain wie Ihr Shop. Cross-origin/externe URLs werden blockiert — in dem Fall zeigt das Plugin stattdessen die eingebaute Bestätigungsseite an und schreibt eine Warnung ins Plugin-Log.

Beispiele:

• Relativer Pfad (empfohlen): /erlebnisse/gutschein-bestaetigung
• Absolut, gleiche Domain: https://ihr-shop.de/danke
• Externe Domain (z. B. https://www.andere-seite.de/...): wird blockiert → Bestätigungsseite statt Weiterleitung

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).

Rate-Limit

Unabhängig vom Token ist der Endpunkt pro IP-Adresse rate-limitiert (max. 2 Anfragen/Minute und 5 Anfragen/Stunde). Bei Überschreitung antwortet er mit HTTP 429 und einem Retry-After-Header. Das begrenzt Missbrauch auch dann, wenn kein Token gesetzt ist.

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 feste Vorlage i7_jtl_voucher_code_delivery (dieselbe wie beim Geburtstags-Gutschein) — nicht die admin-konfigurierte Vorlage für gekaufte Gutscheine. Entsprechend stehen hier andere 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.