Kostenlos testen
Handbuch

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: limit Standard 25, auf 1–50 begrenzt; offset mindestens 0.
  • Mailchimp: count Standard 25, auf 1–100 begrenzt; offset mindestens 0. Kontaktsuche nutzt die Suchantwort des Anbieters ohne eigene Pagination; exact_matches und full_search bleiben beide erhalten.
  • Klaviyo: Seitengröße des jeweiligen Endpunkts; cursor aus page[cursor] in links.next übernehmen, beim Bericht aus page_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.