Newsletter – Brevo, Klaviyo, Mailchimp
Kampagnen, Kennzahlen, Listen, Segmente und Kontakte ausschließlich lesen.
Newsletter-Anbindungen
Die Shared-Tools für Brevo, Klaviyo und Mailchimp lesen Kampagnen, Berichte,
Listen/Segmente und suchen Kontakte. Sie versenden nichts und verändern keine
Kontakte oder Abonnements. Jedes Werkzeug führt genau eine deklarative Anfrage aus.
Alle tragen writes => false und untrusted_output => true: Namen, Inhalte und
Kontaktattribute aus den Antworten bleiben Fremdtext für die zentralen Schutzmechanismen.
Einrichtung je Workspace
Die folgenden Einträge gehören in die apis-Konfiguration des jeweiligen Workspace.
Nur die benötigten Anbieter einrichten, Secret-Marker über dessen Secret-Speicher
auflösen lassen und die gewünschten Tools beim Assistant freigeben. Die Implementierung
aktiviert keine Verbindung und ändert keine bestehenden Workspaces.
return [
'apis' => [
'brevo' => [
'base_url' => 'https://api.brevo.com/v3/',
'headers' => [
'api-key' => '{{secret:BREVO_API_KEY}}',
'Accept' => 'application/json',
],
'read_timeout' => 25,
],
'klaviyo' => [
'base_url' => 'https://a.klaviyo.com/api/',
'headers' => [
'Authorization' => 'Klaviyo-API-Key {{secret:KLAVIYO_API_KEY}}',
'revision' => '2025-10-15',
'Accept' => 'application/vnd.api+json',
'Content-Type' => 'application/vnd.api+json',
],
'read_timeout' => 25,
],
'mailchimp' => [
// us1 durch das Rechenzentrum des eigenen Accounts ersetzen.
'base_url' => 'https://us1.api.mailchimp.com/3.0/',
'headers' => [
'Authorization' => 'Bearer {{secret:MAILCHIMP_API_KEY}}',
'Accept' => 'application/json',
],
'read_timeout' => 25,
],
],
];
Klaviyo: privater API-Key mit campaigns:read, lists:read, segments:read,
profiles:read und für die Metrik-Auswahl metrics:read. Die dokumentierte Revision
ist bewusst fixiert; bei einem Versionswechsel insbesondere den Kanalfilter der
Kampagnenliste prüfen. Keine automatische Umstellung auf eine neue API-Version.
Brevo und Mailchimp: Kontoberechtigungen beim Anbieter beschränken, soweit möglich.
Die nur lesenden Tools machen einen umfassender berechtigten API-Key selbst nicht
zu einem schreibgeschützten Zugang.
Werkzeuge
| Anbieter | Werkzeug | Eingaben / Ergebnis |
|---|---|---|
| Brevo | brevoListCampaigns |
limit, offset; Kampagnen |
| Brevo | brevoGetCampaignReport |
campaign_id als numerischer String; Kampagne mit statistics |
| Brevo | brevoListLists |
limit, offset; Kontaktlisten |
| Brevo | brevoListSegments |
limit, offset; Segmente |
| Brevo | brevoFindContact |
email; exakte Suche, nicht gefunden als API-404 |
| Klaviyo | klaviyoListCampaigns |
cursor; E-Mail-Kampagnen |
| Klaviyo | klaviyoGetCampaignReport |
campaign_id, conversion_metric_id; optional timeframe, cursor |
| Klaviyo | klaviyoListLists |
cursor; Listen |
| Klaviyo | klaviyoListSegments |
cursor; Segmente |
| Klaviyo | klaviyoListMetrics |
cursor; Metriken zur Auswahl von conversion_metric_id |
| Klaviyo | klaviyoFindContact |
email, optional cursor; exakte Profilsuche |
| Mailchimp | mailchimpListCampaigns |
count, offset; Kampagnen |
| Mailchimp | mailchimpGetCampaignReport |
campaign_id; Bericht einer Kampagne |
| Mailchimp | mailchimpListLists |
count, offset; Audiences/Listen |
| Mailchimp | mailchimpListSegments |
list_id, optional count, offset; Segmente einer Liste |
| Mailchimp | mailchimpFindContact |
query (E-Mail oder Name), optional list_id; exakte und ähnliche Treffer |
Klaviyos Bericht verwendet POST ausschließlich als Leseabfrage auf
campaign-values-reports, keinen Versand- oder Erstellungs-Endpunkt. Er liefert
Zustellungen, Öffnungen, Öffnungsrate, Klicks, Klickrate, Abmeldungen und
Conversion-Wert. timeframe: last_30_days (Standard) oder last_12_months.
Die Conversion-Metrik bewusst anhand von klaviyoListMetrics auswählen; sie wird
nicht stillschweigend als Umsatz interpretiert. Kennzahlen, Einheiten und Zeitbezug
bleiben im Anbieterformat; Raten verschiedener Anbieter nicht ungeprüft vergleichen.
Beispiele:
{"tool":"brevoFindContact","args":{"email":"newsletter-test@example.org"}}
{"tool":"klaviyoGetCampaignReport","args":{"campaign_id":"CAMPAIGN_ID","conversion_metric_id":"METRIC_ID","timeframe":"last_30_days"}}
{"tool":"mailchimpListSegments","args":{"list_id":"LIST_ID","count":25,"offset":0}}
Pagination, Fehler und Grenzen
- Eine Seite pro Aufruf, keine automatische Vollabfrage und kein Folgen von Antwort-URLs.
- Brevo:
limitStandard 25, auf 1–50 begrenzt;offsetmindestens 0. - Mailchimp:
countStandard 25, auf 1–100 begrenzt;offsetmindestens 0. Kontaktsuche nutzt die Suchantwort des Anbieters ohne eigene Pagination;exact_matchesundfull_searchbleiben beide erhalten. - Klaviyo: Seitengröße des jeweiligen Endpunkts;
cursorauspage[cursor]inlinks.nextübernehmen, beim Bericht auspage_cursor. Nur den dekodierten Parameterwert übergeben. Er wird als Query-Wert kodiert, niemals als URL ausgeführt. - Listen haben zentrale
disclosure-Anzeige; außerhalb dieser Anzeige bleiben API-Antworten einschließlich Pagination und leerer Treffer unverändert erhalten. - IDs sind auf sichere Zeichen beschränkt, E-Mail-Suchen werden validiert und kodiert. Zusätzliche Argumente gelangen weder in Query noch Reporting-Body.
- HTTP-Fehler bleiben Fehler, insbesondere 401/403 (Zugang/Berechtigung), 404 (nicht gefunden) und 429 (Rate-Limit). Keine erfundenen Null-Kennzahlen bei Fehlern.
- Zentraler Retry: höchstens zwei Versuche bei 429/500/502/503/504, drei Sekunden Abstand. Das ersetzt keinen Anbieter-Rate-Limiter. Bei weiterem 429 später erneut abrufen; insbesondere Klaviyo-Berichte sparsam planen (sehr geringe Kontingente).
- Kein Versand, Import, Exportjob, Abo-Wechsel, Erstellen, Löschen oder Bearbeiten. Kein Live-Zugang getestet; reale Berechtigungen und Kontolimits bleiben ungeprüft.
Prüfung und Quellen
tests/TestCase/Tooling/NewsletterToolsTest.php prüft alle Werkzeuge über den echten
ToolRunner im Read-only-Kontext mit gefälschtem HTTP, synthetischen Antworten und Test-Tokens.
Aufruf: bin/dev-test.sh --filter=NewsletterToolsTest.
Vertragsgrundlagen: Brevo Kampagnen, Berichte, Segmente, Kontaktsuche, Klaviyo Kampagnen (fixierte Revision), Listen, Reporting, Mailchimp Berichte, Segmente, Kontaktsuche.