siteway

// stack · schnittstelle

Mailchimp.

Mailchimp ist ein weit verbreiteter Dienst für E-Mail-Marketing — und er lässt sich an eine Website anbinden, ohne dass ein fremdes Formular in die Seite eingebettet wird. Für siteway heißt das: eigenes Anmeldeformular, eigener serverseitiger Endpunkt, und die Marketing-API dahinter. Diese Seite beschreibt, wie dieser Weg technisch aussieht — und wo das Double-Opt-in darin entsteht.

stack system: mailchimp · e-mail-marketing weg: marketing-api format: json · https seit: 2006

// definition

Was ist Mailchimp?

Mailchimp ist ein weit verbreiteter Dienst für E-Mail-Marketing. Newsletter werden dort geschrieben, versendet und ausgewertet; die Empfänger liegen in einer Audience — der Anbieter beschreibt sie als die Sammlung der eigenen Kontakte und empfiehlt, mit einer einzigen auszukommen und stattdessen innerhalb der Audience zu ordnen.

Geordnet wird mit zwei Mitteln. Merge-Felder sind die zusätzlichen Datenfelder am Kontakt — Vorname, Nachname, was das Mailing sonst noch braucht. Sie gehören jeweils zu einer Audience und werden über ihr Merge-Tag angesprochen, etwa FNAME und LNAME. Tags sind Etiketten, die an einem Kontakt hängen und ihn einordnen: woher er kam, wofür er sich angemeldet hat.

Für eine Website zählt vor allem der Weg nach draußen. Mailchimp bringt eigene, einbettbare Anmeldeformulare mit — und daneben eine öffentlich dokumentierte Marketing-API. Über sie lässt sich ein Kontakt aus einem selbst gebauten Formular heraus eintragen, mit Merge-Feldern und Tags. Genau dieser zweite Weg ist das Thema dieser Seite. Den fertigen Baustein für die Website — Formular, Bestätigung, Consent-Nachweis — beschreibt siteway in der Expertise unter Newsletter & E-Mail.

// praxis

Wie wir Mailchimp anbinden.

eigenes formular · serverseitig

Die Kette hat vier Glieder, und sie ist in jedem Projekt dieselbe. Erstens das Formular: Es gehört zur Website, ist im eigenen Design gebaut, im eigenen Markup verankert und lässt sich mit Tastatur und Screenreader bedienen. Zwei, drei Felder reichen meistens — E-Mail-Adresse, vielleicht der Vorname für die Anrede, dazu die Einwilligung als bewusste Handlung. Wie wir Formulare grundsätzlich bauen, steht unter Formularstrecken.

Zweitens der eigene Endpunkt. Abgeschickt wird nicht zu Mailchimp, sondern an eine eigene Adresse auf demselben Server. Dort passieren die Dinge, die im Browser nichts zu suchen haben: Die Eingabe wird geprüft, Missbrauch wird gebremst, und der API-Schlüssel liegt in der Server-Konfiguration — nie im JavaScript, nie im HTML, nie in einem Repository. Aus dieser Trennung folgt ein angenehmer Nebeneffekt: Im Browser der Besucherin wird kein Fremdcode geladen, weil die Verbindung zum Dienst erst hinter der Website beginnt.

Drittens der Aufruf. Der Server legt den Kontakt in der Audience an — mit dem Status, der zur Anmeldung über eine Website passt: pending. Damit verschickt Mailchimp die Bestätigungsmail, und erst der Klick auf den Link darin macht aus dem Kontakt einen eingetragenen Empfänger. Dazu gehen die vereinbarten Merge-Felder mit und der Tag, der später erkennen lässt, über welches Formular die Anmeldung kam.

Viertens die Rückmeldung. Der Absender erfährt in klarer Sprache, was jetzt passiert: dass eine E-Mail unterwegs ist und dass die Anmeldung erst mit dem Klick darin gilt. Und er erfährt es auch dann, wenn etwas schiefgeht — bei einer ungültigen Adresse, bei einem bereits eingetragenen Kontakt, bei einem abgemeldeten. Nichts davon darf als weiße Seite oder als technischer Fehlertext enden.

Und weil der Dienst irgendwann einmal nicht antwortet: Der Endpunkt protokolliert den Vorgang, versucht es mit Abstand erneut und meldet den Ausfall, statt die Anmeldung stillschweigend zu verlieren. Die buchbare Leistung dahinter beschreiben wir unter Schnittstellen & Integration.

// technik · 6 details

Die Technik im Detail.

belegt aus der doku

Was hier steht, stammt aus der öffentlichen Entwicklerdokumentation von Mailchimp — Pfade, Parameter und Statuswerte im Original. Alles, was dort nicht belegt ist, steht hier auch nicht.

// d-01zugang

Schlüssel & Serverpräfix.

Die Basis-URL ist kontospezifisch: Sie beginnt mit dem Serverpräfix des Kontos, gefolgt von .api.mailchimp.com/3.0/ — etwa us6.api.mailchimp.com/3.0/. Das Präfix steht laut Dokumentation hinter dem Bindestrich am Ende des API-Schlüssels. Authentifiziert wird per Basic-Auth mit beliebigem Benutzernamen und dem Schlüssel als Passwort — alternativ per OAuth-2-Token.

zweck: authentifizierung

// d-02eintrag

Kontakt anlegen.

Ein Kontakt entsteht über POST auf /lists/{list_id}/members. Pflicht sind die E-Mail-Adresse und der Status; optional gehen Merge-Felder und Tags im selben Aufruf mit. Die list_id ist die Kennung der Audience — sie steht in jedem Pfad, der Kontakte betrifft.

zweck: anmeldung

// d-03bestätigung

Der Status entscheidet.

Dokumentiert sind vier Werte: subscribed, unsubscribed, cleaned und pending. Zu pending steht in der Dokumentation, dass dieser Wert zu verwenden ist, um eine Bestätigungsmail zu senden, und dass der Status nach der Bestätigung auf subscribed wechselt. Für eine Anmeldung über die Website ist das der richtige Weg.

zweck: double-opt-in

// d-04aktualisieren

Anlegen oder aktualisieren.

Für den zweiten Anlauf gibt es PUT auf /lists/{list_id}/members/{subscriber_hash}: Existiert der Kontakt, wird er aktualisiert, sonst mit dem Wert aus status_if_new angelegt. Der subscriber_hash ist der MD5-Hash der kleingeschriebenen E-Mail-Adresse und lässt sich serverseitig berechnen.

zweck: keine dubletten

// d-05struktur

Merge-Felder & Tags.

Merge-Felder werden je Audience unter /lists/{list_id}/merge-fields verwaltet und über ihr Merge-Tag angesprochen, etwa FNAME. Tags setzt ein POST auf /lists/{list_id}/members/{subscriber_hash}/tags — mit active zum Setzen und inactive zum Entfernen; ein noch nicht vorhandener Tag wird dabei neu angelegt.

zweck: daten & einordnung

// d-06grenzen

Fehler & Grenzen.

Die Dokumentation nennt eine Grenze von zehn gleichzeitig verarbeiteten Anfragen je Nutzer; darüber antwortet die API mit 429. Dazu kommt ein Zeitlimit von 120 Sekunden je Aufruf. Ein Anmeldeformular berührt das selten — ein Massenabgleich sehr wohl, und er wird entsprechend gedrosselt.

zweck: stabiler betrieb

Abmeldung und Löschung.

Eine Anmeldung ist nur die halbe Strecke. Die Abmeldung ist im Datenmodell eine Statusänderung: Der Kontakt bekommt unsubscribed und bleibt mit seiner Historie erhalten. Daneben steht das Archivieren über einen DELETE-Aufruf auf /lists/{list_id}/members/{subscriber_hash}.

Und schließlich das endgültige Löschen über /lists/{list_id}/members/{subscriber_hash}/actions/delete-permanent, das alle personenbezogenen Daten des Kontakts entfernt. Die Dokumentation weist ausdrücklich darauf hin, dass sich dieser Kontakt danach nicht wieder importieren lässt — der Aufruf ist also kein Aufräumbefehl, sondern eine Entscheidung.

Auf der Website planen wir beides von Anfang an mit ein: den Abmeldelink in jeder Mail, einen nachvollziehbaren Ablauf für Auskunfts- und Löschanfragen, und die Frage, was mit einer Adresse passiert, die sich nach der Abmeldung erneut anmeldet. Diese Fälle im Vorfeld zu klären, kostet ein Gespräch — sie später zu klären, kostet mehr.

// integration

Mailchimp in deine Website integrieren.

drei systeme · ein muster

Der Weg, den wir bauen, ist zuerst einmal systemunabhängig. Auf der Seite steht ein eigenes Anmeldeformular im Design der Website — dieselbe Typografie, dieselben Abstände, dieselben Fehlermeldungen wie überall sonst. Es schickt seine Daten an einen serverseitigen Endpunkt derselben Website. Dort liegt der API-Schlüssel, dort wird die Eingabe geprüft, und von dort geht der Aufruf an die Marketing-API: Eintrag in die Audience mit dem Status pending, also ausstehend. Mailchimp verschickt daraufhin seine Bestätigungsmail; erst der Klick auf den Link darin macht aus dem Eintrag einen bestätigten Empfänger.

Zurück zum Absender geht eine verständliche Rückmeldung — dass eine E-Mail unterwegs ist, dass die Anmeldung erst mit dem Klick gilt, und im Fehlerfall, was genau nicht funktioniert hat. Diese vier Glieder — Formular, Endpunkt, API-Aufruf, Antwort — sind in jedem CMS dieselben. Was sich unterscheidet, ist die Stelle, an der jedes Glied im System sitzt: wo das Formular als Inhaltselement liegt, wie die Route entsteht, wo der Schlüssel hinterlegt wird und womit die Ausgabe gerendert wird.

// cms-01typo3

Mailchimp in TYPO3.

In TYPO3 bauen wir die Anbindung als eigene Extension. Das Anmeldeformular wird darin zum Plugin-Element: Die Redaktion platziert es auf jeder Seite, in jeder Spalte, so oft sie will — im Backend sichtbar wie jedes andere Inhaltselement. Der Endpunkt entsteht als serverseitige Route mit passender Middleware; sie nimmt das abgeschickte Formular entgegen, prüft die Eingabe und ruft die Marketing-API auf. Gerendert wird über Fluid, also mit denselben Templates und Partials wie der Rest der Website. Der API-Schlüssel und die Kennung der Audience liegen in der Extension-Konfiguration und damit außerhalb des Frontends. Mehrsprachige Auftritte bekommen ihre Beschriftungen und Hinweistexte über die Sprachdateien der Extension.

typo3 im stack →

// cms-02wordpress

Mailchimp in WordPress.

In WordPress entsteht die Anbindung als eigenes Plugin und nicht als Theme-Code — so übersteht sie einen Theme-Wechsel und lässt sich unabhängig vom Design aktualisieren. Den Endpunkt bildet eine eigene REST-Route: Sie nimmt die Formulardaten entgegen, prüft sie serverseitig und spricht von dort aus die Marketing-API an. Der API-Schlüssel steht in der wp-config.php oder in einer Umgebungsvariablen, nicht in der Datenbank und nicht im ausgelieferten Markup. Fürs Frontend kommen Template-Dateien dazu sowie Blocks für den Editor, damit die Redaktion das Anmeldeformular dort setzt, wo es hingehört — im Beitrag, in einer Seitenleiste oder unter einem Artikel.

wordpress im stack →

// cms-03statamic

Mailchimp in Statamic.

Statamic läuft auf Laravel — und damit liegt der Endpunkt genau dort, wo man ihn erwartet: eine Route plus Controller, mit der Validierung als eigenem Schritt davor. Das Formularmodell beschreibt ein Blueprint: welche Felder es gibt, welche Pflicht sind, wie sie beschriftet werden und welches Feld auf welches Merge-Feld geht. Der API-Schlüssel und die Kennung der Audience stehen in der .env-Datei und werden über die Konfiguration gelesen. Gerendert wird mit Antlers oder Blade, also mit denselben Mitteln wie der Rest des Frontends. Läuft Static Caching, bleibt das Formular davon unberührt, weil der Endpunkt eine eigene Route ist und nicht Teil der zwischengespeicherten Seite.

statamic im stack →

// datenschutz

Was vorher zu klären ist.

sachlich, kein rechtsrat

Eine E-Mail-Adresse ist ein personenbezogenes Datum, und sie wird bei einer Newsletter-Anmeldung an einen Dienstleister übergeben. Mailchimp wird von der The Rocket Science Group LLC betrieben, einem Unternehmen aus den USA — daraus folgen zwei Punkte, die vor dem Go-live geklärt gehören: die Auftragsverarbeitung und der Datentransfer.

Der Anbieter stellt dafür ein Data Processing Addendum bereit. Darin beschreibt er sich als Auftragsverarbeiter, der Kundendaten im Auftrag verarbeitet, und benennt als Grundlagen für die Übermittlung unter anderem die Standardvertragsklauseln und den EU-US Data Privacy Framework. Dass es dieses Dokument gibt, ist eine Tatsache; wie es im konkreten Fall zu bewerten ist, entscheidet ihr mit eurer Rechtsberatung. Wer die Verarbeitung innerhalb der EU halten möchte, wählt einen Anbieter, der genau das zusichert — an der Technik der Anbindung ändert das nichts. Die Schwesterseiten zu CleverReach und rapidmail beschreiben deren Schnittstellen im selben Aufbau.

Was wir technisch beisteuern, ist die saubere Seite der Website. Datensparsamkeit im Formular: nur Felder, die sich begründen lassen. Die Einwilligung als bewusste Handlung, getrennt vom Absenden und mit klarer Beschreibung, wofür sie gilt. Die Übertragung ausschließlich serverseitig über TLS. Das Double-Opt-in über den Status pending, sodass ein Nachweis entsteht, statt behauptet zu werden. Und benannte Wege für Abmeldung und Löschung, bevor die erste Anfrage kommt.

Ein Nebeneffekt der Bauweise gehört hierher: Weil das Formular selbst gebaut ist und die Übergabe serverseitig läuft, lädt im Browser der Besucherin kein Fremdcode. Der Browser spricht mit der Website, die Website spricht mit dem Dienst. Wie wir Seiten grundsätzlich trackingfrei und mit sauberen Security-Headern ausliefern, steht unter Sicherheit & Datenschutz.

// faq

Häufige Fragen.

Was ist Mailchimp?

Mailchimp ist ein weit verbreiteter Dienst für E-Mail-Marketing. Kontakte liegen dort in einer Audience — Mailchimp selbst beschreibt sie als die Sammlung deiner Kontakte und empfiehlt, mit einer einzigen auszukommen. An jedem Kontakt hängen Merge-Felder für zusätzliche Daten wie Vor- und Nachname und Tags zur Einordnung. Für die Website ist vor allem eines wichtig: Mailchimp dokumentiert seine Marketing-API öffentlich, sodass eine Anmeldung nicht über ein eingebettetes Fremdformular laufen muss, sondern über ein eigenes Formular und einen serverseitigen Endpunkt gehen kann.

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

Über einen serverseitigen Zwischenschritt. Das Anmeldeformular gehört zur Website, ist also im eigenen Design gebaut und im eigenen Markup verankert. Abgeschickt wird es an einen eigenen Endpunkt auf demselben Server. Dort wird die Eingabe geprüft, und erst von dort geht der Aufruf an die Marketing-API. Die Basis-URL ist dabei kontospezifisch: Sie beginnt mit dem Serverpräfix des Kontos, gefolgt von .api.mailchimp.com/3.0/ — also etwa us6.api.mailchimp.com/3.0/. Das Serverpräfix steht laut Dokumentation hinter dem Bindestrich am Ende des API-Schlüssels. Authentifiziert wird per HTTP-Basic-Authentifizierung, bei der ein beliebiger Benutzername und der API-Schlüssel als Passwort übergeben werden; alternativ ist ein OAuth-2-Token möglich. Der Kontakt selbst entsteht über einen POST-Aufruf auf /lists/{list_id}/members mit E-Mail-Adresse und Status.

Löst die API die Bestätigungsmail für das Double-Opt-in aus?

Ja, und zwar über den Status, mit dem der Kontakt angelegt wird. Die Dokumentation nennt vier Werte: subscribed für einen Kontakt, der Kampagnen empfangen kann, unsubscribed für einen abgemeldeten, cleaned für einen, dessen Adresse zurückgekommen ist, und pending für einen, der die Aufnahme mit Double-Opt-in angefragt, aber noch nicht bestätigt hat. Zu pending steht dort wörtlich, dass dieser Wert zu verwenden ist, um eine Bestätigungsmail zu senden, und dass der Status nach der Bestätigung auf subscribed wechselt. Für eine Anmeldung über die Website ist deshalb pending der richtige Weg: Die Bestätigungsmail verschickt Mailchimp, der Link darin führt zurück zum Dienst, und erst danach ist der Kontakt eingetragen. Der Wert subscribed trägt dagegen direkt ein, ohne Bestätigungsschritt.

Was sind Audience, Merge-Felder und Tags?

Die drei Bausteine des Datenmodells. Die Audience ist der Verteiler, in dem die Kontakte liegen; jeder API-Aufruf für Kontakte trägt ihre Kennung als list_id im Pfad. Merge-Felder sind die zusätzlichen Datenfelder am Kontakt, verwaltet je Audience unter /lists/{list_id}/merge-fields und angesprochen über ihr Merge-Tag, etwa FNAME und LNAME. Tags sind Etiketten zur Einordnung; sie werden über /lists/{list_id}/members/{subscriber_hash}/tags gesetzt, mit dem Status active zum Setzen und inactive zum Entfernen, und ein noch nicht vorhandener Tag wird beim Setzen neu angelegt. Für die Website heißt das: Welches Formularfeld auf welches Merge-Feld geht und welcher Tag ein Anmeldeformular kennzeichnet, wird vor dem Bauen festgelegt — nicht nachträglich im Verteiler aufgeräumt.

Was passiert, wenn eine Adresse schon in der Audience liegt?

Dafür gibt es einen eigenen, dokumentierten Weg. Neben dem POST-Aufruf zum Anlegen kennt die API den PUT-Aufruf auf /lists/{list_id}/members/{subscriber_hash}: Existiert der Kontakt, wird er aktualisiert; existiert er nicht, wird er mit dem Wert aus status_if_new angelegt — auch hier stehen subscribed, unsubscribed, cleaned und pending zur Auswahl. Der subscriber_hash ist dabei kein Zufallswert, sondern der MD5-Hash der kleingeschriebenen E-Mail-Adresse, lässt sich also auf dem eigenen Server berechnen. Wichtig ist die Rückmeldung nach vorn: Der Absender bekommt eine verständliche Antwort, statt in einen technischen Fehler zu laufen, und bei einem bereits eingetragenen oder abgemeldeten Kontakt entscheidet die Fehlerbehandlung, was angezeigt wird.

Wie laufen Abmeldung und Löschung?

Beides sind zwei verschiedene Dinge, und beide sind dokumentiert. Die Abmeldung ist eine Statusänderung: Der Kontakt bekommt den Status unsubscribed und bleibt mit seiner Historie erhalten. Daneben steht das Archivieren über einen DELETE-Aufruf auf /lists/{list_id}/members/{subscriber_hash}. Und schließlich gibt es das endgültige Löschen über /lists/{list_id}/members/{subscriber_hash}/actions/delete-permanent, das alle personenbezogenen Daten des Kontakts entfernt; die Dokumentation weist darauf hin, dass sich dieser Kontakt danach nicht wieder importieren lässt. Auf der Website planen wir beide Wege mit ein: den Abmeldelink in jeder Mail und einen Ablauf für Auskunfts- und Löschanfragen, damit sie nicht am Support hängen bleiben.

Was ist beim Datenschutz zu beachten, wenn Mailchimp ein US-Anbieter ist?

Mailchimp wird von der The Rocket Science Group LLC betrieben, einem Unternehmen aus den USA. Damit sind zwei Punkte zu klären, bevor die Anbindung live geht: die Auftragsverarbeitung und der Datentransfer. Der Anbieter stellt dafür ein Data Processing Addendum bereit, in dem er sich als Auftragsverarbeiter beschreibt und das die Standardvertragsklauseln sowie den EU-US Data Privacy Framework als Grundlagen für die Übermittlung benennt. Was davon im konkreten Fall trägt, gehört in die Bewertung durch die eigene Rechtsberatung — wir liefern die technische Seite: Datensparsamkeit im Formular, serverseitige Übertragung, dokumentiertes Double-Opt-in, benannte Löschwege. Wer die Verarbeitung innerhalb der EU halten möchte, entscheidet sich für einen Anbieter, der genau das zusichert; die Technik der Anbindung bleibt dieselbe.

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

Ja, in allen dreien — und zwar so, dass die Anbindung Teil der Website ist und nicht daneben liegt. In TYPO3 bauen wir eine eigene Extension: das Anmeldeformular als Plugin-Element, das die Redaktion auf jeder Seite platziert, eine serverseitige Route mit passender Middleware als Endpunkt, Fluid für die Ausgabe und den API-Schlüssel in der Extension-Konfiguration. In WordPress entsteht ein eigenes Plugin statt Theme-Code, damit die Anbindung einen Theme-Wechsel übersteht: eine eigene REST-Route nimmt das Formular entgegen, der Schlüssel liegt in der wp-config.php oder in einer Umgebungsvariablen, ausgegeben wird über Template-Dateien und Blocks für den Editor. In Statamic liegt Laravel darunter: Route plus Controller als Endpunkt, ein Blueprint für das Formularmodell, der Schlüssel in der .env-Datei, gerendert mit Antlers oder Blade. Gemeinsam ist allen dreien, dass der Schlüssel serverseitig bleibt und im Browser der Besucherin kein Fremdcode geladen wird.

// Newsletter-Anmeldung auf deiner Website?

Projekt anfragen