siteway

// stack · schnittstelle

CleverReach.

CleverReach ist ein E-Mail-Marketing-Dienst aus Deutschland — und für siteway vor allem eine Schnittstelle: eine dokumentierte REST-API, über die eine Anmeldung auf der Website im Verteiler landet. Diese Seite beschreibt die Technik dahinter — vom eigenen Formular über den serverseitigen Endpunkt bis zum Double-Opt-In, das der Dienst auslöst.

stack system: cleverreach · e-mail-marketing weg: rest-api v3 · oauth 2.0 einwilligung: double-opt-in seit: 2006

// definition

Was ist CleverReach?

CleverReach ist ein E-Mail-Marketing-Dienst der CleverReach GmbH & Co. KG mit Sitz in Rastede in Niedersachsen. Newsletter und automatisierte E-Mail-Strecken werden darin im Browser gebaut, versendet und ausgewertet. Die Empfänger liegen in Gruppen, Zusatzfelder wie Anrede oder Interesse hängen als Attribute am einzelnen Empfänger.

Für deutsche Auftraggeber ist ein Punkt regelmäßig ausschlaggebend, und er lässt sich nüchtern benennen: Der Anbieter sitzt in Deutschland und gibt an, die Daten ausschließlich auf Servern in Deutschland und der EU zu speichern. Das ersetzt keine eigene Prüfung und keinen Vertrag — aber es verkürzt die Diskussion über den Drittlandtransfer, die bei Diensten außerhalb der EU zuerst geführt werden muss.

Interessant wird das System an der Stelle, an der es die Website berührt: CleverReach dokumentiert eine REST-API in Version 3 unter rest.cleverreach.com, mit Endpunkten für Gruppen, Empfänger, Attribute und Formulare sowie Webhooks für den Rückweg. Damit muss eine Anmeldung nicht als fremdes Formular in die Seite geklebt werden — sie kann Teil der Website sein und trotzdem im Verteiler ankommen.

// praxis

Wie wir CleverReach anbinden.

eigenes formular · serverseitig

Die erste Entscheidung fällt am Formular: Es gehört zur Website. Eigenes Markup, eigenes Design, eigene Fehlermeldungen, eigene Fokus-Reihenfolge — dieselbe Sorgfalt wie bei jeder anderen Formularstrecke. Ein Anmeldefeld, das aussieht wie der Rest der Seite und sich auch so bedient, wird ausgefüllt. Eines, das sichtbar aus einem fremden System stammt, unterbricht den Ablauf genau in dem Moment, in dem jemand zusagen wollte.

Abgeschickt wird an einen Endpunkt auf dem eigenen Server. Der prüft zuerst die Eingabe: Ist das überhaupt eine E-Mail-Adresse, ist die Einwilligung gesetzt, kommt die Anfrage aus dem eigenen Formular, kommen aus derselben Richtung gerade auffällig viele Einträge. Erst danach spricht er mit CleverReach — mit einem Zugriffstoken, das ausschließlich hier liegt. Die Zugangsdaten sehen den Browser nie. Was im Frontend steht, kann jeder lesen, und wer das Token hat, hat den ganzen Verteiler.

Dann folgt der Kern: Der Endpunkt trägt die Adresse in die vorgesehene Empfängergruppe ein — ausdrücklich als noch nicht bestätigt — und lässt CleverReach die Bestätigungsmail verschicken. Der Klick in dieser Mail macht die Adresse zum aktiven Empfänger, nicht das Absenden des Formulars. Dazu gibt der Endpunkt die Daten mit, die den Vorgang später nachvollziehbar machen: Zeitpunkt, Herkunft der Anfrage und über welches Formular sie kam.

Zurück an den Besucher geht eine ehrliche Rückmeldung. Nicht „Du bist angemeldet“, sondern der Hinweis, dass eine Bestätigungsmail unterwegs ist und der Link darin geklickt werden muss — mit einem Wort zum Spam-Ordner. Diese eine Zeile entscheidet darüber, wie viele Anmeldungen tatsächlich ankommen. Für Fehler gilt dieselbe Klarheit: Antwortet die Schnittstelle nicht, wird der Vorgang protokolliert und erneut versucht, und der Besucher bekommt eine Meldung, die ihm sagt, was er tun kann — statt eines stillen Formulars, das scheinbar nichts getan hat.

Zuletzt die Felder. Neben der Adresse nehmen wir nur auf, was später wirklich einen Unterschied macht — Anrede, Vorname, ein Interessengebiet, dazu ein Vermerk, über welches Formular der Eintrag kam. Diese Angaben landen als Attribute am Empfänger und tragen später die Segmentierung. Und weil eine Liste nicht nur wächst: Abmeldung und Löschung denken wir von Anfang an mit, samt Rückmeldung an die Website, wenn sich im Verteiler etwas ändert.

Die Kette im Überblick.

Fünf Stationen, und keine davon ist optional. Erstens das Formular auf der Website. Zweitens der Endpunkt auf dem eigenen Server, der prüft und weiterreicht. Drittens der Eintrag in die Empfängergruppe, ausdrücklich als unbestätigt. Viertens die Bestätigungsmail von CleverReach mit dem eindeutigen Link. Fünftens der Klick, der aus dem Eintrag einen aktiven Empfänger macht.

Wer wissen will, wo das Formular auf der Seite steht, welche Texte daneben stehen und wie der Baustein als Ganzes gebucht wird, findet das in der Komponente Newsletter & E-Mail. Steht hinter der Adresse ein Download statt eines Verteilers, ist das die Komponente Lead-Magnet-Formulare. Diese Seite bleibt bei der Schnittstelle und ihrer Technik.

// technik · 6 details

Die Technik im Detail.

belegt aus der doku

Was hier steht, stammt aus der öffentlichen Entwicklerdokumentation von CleverReach — Endpunkte, Feldnamen und Ereignisnamen im Original. Feste Zahlen zu Anfragegrenzen nennt sie nicht, deshalb behandeln wir die Schnittstelle als knappe Ressource: einzelne Anmeldungen einzeln, größere Mengen gebündelt, nichts unnötig wiederholen.

// d-01zugang

OAuth & Token.

Die Basis ist rest.cleverreach.com/v3, authentifiziert wird nach OAuth 2.0. Im CleverReach-Konto entsteht unter Account, Extras, REST API eine eigene OAuth-Anwendung mit Client ID und Client Secret. Das Zugriffstoken kommt vom Token-Endpunkt und reist als Bearer-Token im Authorization-Header mit; ein Refresh-Token hält den Zugang am Leben.

zweck: authentifizierung

// d-02gruppen

Empfängergruppen.

Empfänger liegen in Gruppen, und Gruppen liegen unter /v3/groups — auslesen, anlegen, umbenennen, entfernen. Für die Website heißt das: Jedes Formular bekommt eine feste Zielgruppe, deren Kennung in der Konfiguration steht. Mehrere Anmeldestellen können in dieselbe Gruppe schreiben oder bewusst in getrennte.

zweck: verteiler

// d-03empfänger

Empfänger anlegen.

Angelegt wird über /v3/groups/{group_id}/receivers, aktualisiert über denselben Pfad mit der Adresse dahinter. Ein Datensatz kennt unter anderem email als Pflichtfeld, registered und activated als Zeitpunkte sowie source für die Herkunft. Steht activated auf null, ist der Empfänger nicht aktiv und bekommt keinen Newsletter — genau der Zustand nach dem Absenden des Formulars.

zweck: eintrag

// d-04einwilligung

Double-Opt-In auslösen.

Die Formulare des Dienstes liegen unter /v3/forms; jedes trägt die Bestätigungsmail mit dem eindeutigen Link. Ausgelöst wird sie über /v3/forms/{form_id}/send/activate mit der Adresse und einem Objekt doidata, das die Angaben zum Vorgang aufnimmt — IP-Adresse, Referrer und User-Agent. Diese Angaben dokumentieren, aus welchem Kontext die Anmeldung kam.

zweck: bestätigungsmail

// d-05felder

Attribute & Segmente.

Zusatzfelder heißen bei CleverReach Attribute. Global gelten sie über /v3/attributes, gruppenbezogen über /v3/groups/{group_id}/attributes; am Empfänger tauchen sie als global_attributes und attributes auf, etwa für Vorname, Nachname oder Anrede. Genau daraus entstehen später Segmente — deshalb wird beim Formular entschieden, welches Feld überhaupt sinnvoll ist.

zweck: segmentierung

// d-06rückweg

Webhooks.

Damit die Website erfährt, was im Verteiler passiert, registrieren wir einen Webhook über hooks/eventhook — anlegen, auflisten, je Ereignis wieder entfernen. Dokumentiert sind unter anderem receiver.subscribed, receiver.unsubscribed, receiver.created, receiver.updated und receiver.deleted. Der Rückweg zählt überall dort, wo derselbe Kontakt auch in einem anderen System steht.

zweck: ereignisse

Wann welcher Weg passt.

Es gibt zwei Wege, wie eine Anmeldung nach CleverReach kommt, und beide sind legitim. Der eine nutzt die Formulare des Dienstes: CleverReach stellt sie bereit, sie sind schnell eingerichtet und funktionieren ohne eigenen Code. Der andere ist das eigene Formular mit serverseitigem Endpunkt, wie diese Seite es beschreibt.

Die Zuordnung ist keine Rangliste. Geht es um eine einzelne Anmeldestelle, soll es schnell gehen und ist das Erscheinungsbild zweitrangig, tragen die Formulare des Dienstes. Soll die Anmeldung Teil der Website sein — an mehreren Stellen, im gleichen Design, mit eigener Validierung, eigenen Feldern für die Segmentierung, eigener Danke-Seite und ohne Fremdcode im Browser des Besuchers — dann führt der Weg über den eigenen Endpunkt.

Was in einem Projekt trägt, klären wir im Konzept, bevor gebaut wird — zusammen mit der Frage, ob der Kontakt außer im Verteiler noch woanders gebraucht wird. Die buchbare Leistung dahinter beschreibt siteway unter Schnittstellenentwicklung.

// integration

CleverReach in deine Website integrieren.

drei systeme · ein muster

Der Weg ist in jedem System derselbe, weil er nicht am CMS hängt, sondern an der Schnittstelle. Auf der Seite steht ein eigenes Anmeldeformular im Design der Website — dort, wo es hingehört: im Footer, im Artikel, auf einer eigenen Seite. Abgeschickt wird an einen serverseitigen Endpunkt, der die Zugangsdaten hält und die Eingabe prüft. Der trägt die Adresse in die Empfängergruppe ein, ausdrücklich als noch nicht bestätigt, und lässt anschließend CleverReach die Double-Opt-In-Mail auslösen. Zurück an den Absender geht eine Rückmeldung, die sagt, was jetzt passiert: Bestätigungsmail prüfen, Link klicken, fertig.

Was sich zwischen den Systemen unterscheidet, sind drei Dinge: wo das Formular herkommt, wie die Route zum Endpunkt entsteht und wo die Zugangsdaten liegen. Für jedes dieser drei Dinge bringt jedes System eine eigene, saubere Antwort mit — und in allen drei Fällen bauen wir die Anbindung selbst, damit sie zum Projekt passt und nicht das Projekt zu ihr. Die Redaktion soll die Anmeldung danach ohne uns platzieren können; die Technik darunter bleibt an einer Stelle.

// cms-01typo3

CleverReach in TYPO3.

In TYPO3 bauen wir die Anbindung als eigene Extension. Das Anmeldeformular wird ein Plugin-Element, das die Redaktion auf jeder Seite platziert — im Footer über ein Referenz-Element, im Artikel als Inhaltselement, auf einer eigenen Seite als Ganzes. Die Übergabe an CleverReach läuft über eine serverseitige Route mit passender Middleware, die die Eingabe prüft, den Empfänger anlegt und die Bestätigungsmail auslöst. Gerendert wird mit Fluid, sodass Feldbeschriftungen, Hinweistexte und Fehlermeldungen im Template stehen und nicht im Code. Die Zugangsdaten liegen in der Konfiguration der Extension, getrennt vom Inhalt und aus dem Frontend nicht erreichbar.

typo3 im stack →

// cms-02wordpress

CleverReach in WordPress.

In WordPress entsteht die Anbindung als eigenes Plugin und nicht als Theme-Code — so überlebt sie den nächsten Theme-Wechsel. Eine eigene REST-Route nimmt die Anmeldung entgegen, prüft sie serverseitig, trägt den Empfänger in die Gruppe ein und stößt die Bestätigungsmail an. Die Zugangsdaten stehen in der wp-config.php oder in einer Umgebungsvariable, nie in der Datenbank und nie im ausgelieferten Markup. Fürs Frontend kommen Template-Dateien und Blocks für den Editor dazu, damit die Redaktion das Formular dort einsetzt, wo es wirken soll — und der Datenschutzhinweis daneben redaktionell pflegbar bleibt.

wordpress im stack →

// cms-03statamic

CleverReach in Statamic.

Statamic läuft auf Laravel, und das macht diesen Teil besonders geradlinig: Eine Route plus Controller nimmt die Anmeldung an, validiert sie mit den Bordmitteln des Frameworks und spricht anschließend mit der CleverReach-API. Ein Blueprint beschreibt das Formularmodell, also welche Felder es gibt und welche Pflicht sind — pflegbar im Control Panel statt im Code. Die Zugangsdaten stehen in der .env, wie bei jedem anderen Dienst im Projekt. Gerendert wird mit Antlers oder Blade, und weil die Anmeldung eine echte Seite mit echtem Formular ist, funktioniert sie auch mit Static Caching davor.

statamic im stack →

// datenschutz

Datenschutz in der Anbindung.

dokumentieren statt hoffen

Eine Newsletter-Anmeldung verarbeitet personenbezogene Daten, und zwar von der ersten Sekunde an. Deshalb ist Datenschutz hier keine Fußnote, sondern Teil der Bauweise. Der wichtigste Punkt ist schon beschrieben: Die Einwilligung wird dokumentiert, nicht angenommen. Das Double-Opt-In liefert dafür den Beleg — den Zeitpunkt des Eintrags, den Zeitpunkt der Bestätigung und die Angaben zum Vorgang, die beim Auslösen der Bestätigungsmail mitgehen.

Dazu kommt Datensparsamkeit. Pflicht ist die E-Mail-Adresse, alles andere muss sich rechtfertigen: Wenn ein Feld später kein Segment füllt und keine Ansprache verbessert, fragen wir es nicht ab. Am Formular steht ein Hinweis, was mit den Daten passiert, mit Verweis auf die Datenschutzerklärung, und die Einwilligung wird aktiv gegeben — nicht über ein Häkchen, das schon gesetzt ist.

Ein Punkt, der leicht übersehen wird: Ist das Formular selbst gebaut, lädt der Browser des Besuchers keinen Fremdcode. Es gibt kein eingebettetes Skript eines Drittanbieters, das beim Seitenaufruf mitliest, keine Verbindung zu einem fremden Host, bevor jemand überhaupt etwas ausgefüllt hat. Der einzige, der mit CleverReach spricht, ist der eigene Server — und er tut es erst, wenn das Formular abgeschickt wurde.

Organisatorisch gehört ein Auftragsverarbeitungsvertrag dazu, weil der Dienst die Daten im Auftrag verarbeitet — genauso wie beim Hoster. Nach Angaben des Anbieters liegen die Daten auf Servern in Deutschland und der EU, was die Prüfung verkürzt, sie aber nicht ersetzt. Dazu kommen Abmeldung und Löschung als eingebauter Weg, nicht als Sonderfall. Wo eine Website insgesamt steht, zeigt ein Datenschutz-Audit; die technischen Grundlagen stehen im Stack unter Sicherheit & Datenschutz. Was im Einzelfall rechtlich gilt, klärt eine Rechtsberatung — wir bauen die Technik, die eine solche Prüfung überhaupt beantwortbar macht.

// faq

Häufige Fragen.

Was ist CleverReach?

CleverReach ist ein E-Mail-Marketing-Dienst der CleverReach GmbH & Co. KG mit Sitz in Rastede in Niedersachsen. Newsletter und automatisierte E-Mail-Strecken werden im Browser gebaut, versendet und ausgewertet, die Empfänger liegen dabei in Gruppen. Nach Angaben des Anbieters werden die Daten ausschließlich auf Servern in Deutschland und der EU gespeichert. Für die Website zählt vor allem eines: CleverReach dokumentiert eine REST-API in Version 3 öffentlich. Darüber lässt sich eine Anmeldung, die auf der Website steht, sauber an den Verteiler übergeben.

Wie kommt eine Newsletter-Anmeldung von der Website nach CleverReach?

Über eine Kette aus vier Stationen. Die Besucherin füllt ein Anmeldeformular aus, das im Design der Website steht und zu ihr gehört. Das Formular schickt seine Daten an einen Endpunkt auf dem eigenen Server, nicht direkt an CleverReach. Dieser Endpunkt prüft die Eingabe, holt sich ein Zugriffstoken und trägt die Adresse über die REST-API in die vorgesehene Empfängergruppe ein. Danach löst er die Bestätigungsmail beim Dienst aus und meldet der Seite zurück, dass die Bestätigung unterwegs ist. Erst der Klick in dieser Mail macht die Adresse zu einem aktiven Empfänger.

Was ist Double-Opt-In und warum löst CleverReach die Bestätigungsmail aus?

Double-Opt-In bedeutet, dass eine eingetragene Adresse erst dann in den Verteiler kommt, wenn der Inhaber des Postfachs einen eindeutigen Link in einer Bestätigungsmail angeklickt hat. Die Kette lautet: Formular, Eintrag als noch nicht bestätigt, Bestätigungsmail des Dienstes, Klick, aktiver Empfänger. Dass CleverReach diese Mail auslöst und nicht die Website, hat einen praktischen Grund: Der Dienst kennt den Bestätigungslink, protokolliert den Klick und verwaltet den Status des Empfängers. Die Website müsste das sonst parallel nachbauen und beide Stände auseinanderhalten.

Warum darf die Website den Empfänger nicht direkt als bestätigt anlegen?

Weil ein Formular allein nichts beweist. Jeder kann eine fremde Adresse in ein Anmeldefeld tippen. Legt die Website den Empfänger sofort als aktiv an, steht im Verteiler eine Adresse, für die niemand zugestimmt hat, und der erste Newsletter geht an eine Person, die davon nichts weiß. Technisch heißt die Regel deshalb: Beim Anlegen bleibt der Empfänger unbestätigt, und erst der Klick in der Bestätigungsmail schaltet ihn aktiv. In der API bildet das Feld activated genau diesen Zustand ab. Was im Einzelfall rechtlich gilt, klärt eine Rechtsberatung; wir bauen das Verfahren technisch so, dass die Bestätigung nachvollziehbar dokumentiert ist.

Wie funktioniert die CleverReach-API?

Die dokumentierte Version 3 liegt unter rest.cleverreach.com/v3. Authentifiziert wird nach OAuth 2.0: Im CleverReach-Konto entsteht unter Account, Extras, REST API eine OAuth-Anwendung mit Client ID und Client Secret, das Zugriffstoken kommt vom Token-Endpunkt und reist danach als Bearer-Token im Authorization-Header mit. Empfängergruppen liegen unter /v3/groups, Empfänger unter /v3/groups/{group_id}/receivers, Attribute für Zusatzfelder unter /v3/attributes. Ein Empfängerdatensatz kennt unter anderem email, registered, activated, source sowie global_attributes für Felder wie Vorname und Nachname. Für die Bestätigungsmail gibt es /v3/forms und den Aufruf /v3/forms/{form_id}/send/activate.

Wo liegen die Zugangsdaten für die Schnittstelle?

Auf dem Server, nie im Browser. Client ID, Client Secret und das daraus erzeugte Token gehören in die Konfiguration der Anwendung oder in eine Umgebungsvariable, nicht in JavaScript, nicht in ein Datenattribut im Markup und nicht in ein verstecktes Formularfeld. Der Grund ist simpel: Alles, was der Browser lädt, kann jeder lesen. Wer das Token hat, kann den kompletten Verteiler auslesen und verändern. Deshalb spricht ausschließlich der eigene Endpunkt mit CleverReach, und das Formular auf der Seite spricht ausschließlich mit dem eigenen Endpunkt.

Was passiert bei einer Abmeldung?

Die Abmeldung läuft über den Link, den CleverReach in jede Mail setzt, und der Dienst führt den Empfänger danach als nicht mehr aktiv. Damit die Website davon erfährt, registrieren wir einen Webhook: CleverReach meldet Ereignisse wie receiver.unsubscribed oder receiver.deleted an eine Adresse auf dem eigenen Server. Das ist überall dort wichtig, wo der Kontakt auch in einem anderen System steht, etwa im Kundenkonto. Ohne diesen Rückweg bleibt in der Website ein Häkchen stehen, das im Verteiler längst gefallen ist.

Lässt sich CleverReach in TYPO3, WordPress oder Statamic integrieren?

Ja, in alle drei. Die Anbindung bauen wir jeweils selbst, mit den Bordmitteln des Systems. In TYPO3 entsteht eine eigene Extension: das Anmeldeformular als Plugin-Element, eine serverseitige Route mit Middleware für die Übergabe an CleverReach, Fluid für die Ausgabe, die Zugangsdaten in der Konfiguration der Extension. In WordPress entsteht ein eigenes Plugin statt Theme-Code, mit einer eigenen REST-Route als Endpunkt, den Zugangsdaten in der wp-config.php oder einer Umgebungsvariable und Template-Dateien beziehungsweise Blocks fürs Frontend. In Statamic liegt Laravel darunter: Route plus Controller nehmen die Anmeldung an, ein Blueprint beschreibt das Formularmodell, die Zugangsdaten stehen in der .env, gerendert wird mit Antlers oder Blade. Die Kette dahinter ist in allen drei Fällen dieselbe.

// Newsletter-Anmeldung auf deiner Website an CleverReach anbinden?

Projekt anfragen