Was ist die Benchmark Email API? Funktionen, Preise, Anwendung und ein Google-Sheets-Integrationsbeispiel

Das E-Mail-Marketing-Tool „Benchmark Email“ bietet eine offizielle API, mit der Sie Kontakt- und Kampagneninformationen mit externen Tools austauschen können. Sie können Daten aus E-Commerce-Systemen, Buchungstools, CRMs, Google Sheets und mehr automatisch mit Benchmark Email synchronisieren. Das befreit Sie von der lästigen Routine, „wöchentlich CSV-Dateien zu exportieren und wieder zu importieren“.

In diesem Artikel erkläre ich auf Basis der offiziellen Dokumentation vom Oktober 2026 im Detail, was die Benchmark Email API leistet, welche Möglichkeiten und Grenzen sie hat, wie die Nutzungsbedingungen aussehen, wie Sie einen API-Schlüssel erhalten und wie eine konkrete Integration mit Google Sheets aussieht.

Was ist die Benchmark Email API?

Die Benchmark Email API ist eine Schnittstelle, um Ihr Benchmark Email-Konto mit externer Software zu verbinden. Die offizielle Seite bewirbt dies unter dem Motto, dass „Ihr Tech-Stack nahtlos zusammenarbeiten sollte“, und hebt folgende Merkmale hervor:

• JSON over HTTP (ein gängiges REST-Format) sowie eine veröffentlichte OpenAPI-Spezifikation
• Authentifizierung über einen API-Schlüssel (im Header X-API-Key)
• Granulare Berechtigungen (Scopes), mit denen Sie den Zugriff auf Kontakte, Kampagnen, Berichte und Domains einschränken können
• Sie können für jeden Schlüssel ein Ablaufdatum festlegen sowie Schlüssel deaktivieren und wieder aktivieren, ohne sie löschen zu müssen
• Es gibt Rate Limits pro Stunde und Monat, und Sie können das verbleibende Kontingent direkt in den Antwort-Headern einsehen
• Es gibt Szenario-Leitfäden für gängige Workflows sowie einen Migrationsleitfaden von Benchmark Classic

Wichtig zu wissen: Die API kann in allen Tarifen ohne zusätzliche Kosten genutzt werden. Alles, was Sie brauchen, ist ein aktives Konto und ein API-Schlüssel.

Für wen ist die API gedacht?

Auf der offiziellen Seite wird die API als Lösung für folgende Probleme vorgestellt:

• Kundendaten aus Ihrem Online-Shop, Leads aus Tabellen und Kontakte aus dem Kassensystem oder CRM existieren getrennt voneinander
• Sie müssen zum Aufbau Ihrer E-Mail-Liste ständig den Kreislauf aus CSV-Export → Bereinigung → Import wiederholen
• Sie kopieren Kampagnenergebnisse jedes Mal manuell in Tabellen oder Präsentationen

Mit anderen Worten richtet sich die API an Teams, deren Daten auf mehrere Tools verteilt sind und die Datensätze manuell abgleichen. Wenn hingegen alles direkt über die Benutzeroberfläche von Benchmark Email abgewickelt wird, ist die API nicht erforderlich.

Was Sie mit der Benchmark Email API tun können

Die Ressourcen, auf die Sie über die API zugreifen können, lassen sich in vier Hauptgruppen unterteilen:

Kontakte verwalten

Kontakte sind der Bereich, den Sie am häufigsten nutzen werden.

• Kontakte erstellen, aktualisieren und löschen: Anhand der E-Mail-Adresse als Schlüssel können Sie Kontakte samt Namen und beliebigen benutzerdefinierten Feldern registrieren.
• Suche und Segmente: Sie können nach E-Mail-Adresse, E-Mail-Domain, benutzerdefinierten Feldern, Tags, Listen, Status, Erstellungs- sowie Aktualisierungsdatum und mehr suchen. Dabei stehen Ihnen diverse Operatoren wie „gleich“, „enthält“, „beginnt mit“, „innerhalb eines Zeitraums“ oder „ist leer“ zur Verfügung, die sich per UND/ODER verknüpfen lassen.
• Duplikatsprüfung: Wenn Sie vor dem Erstellen eines Kontakts nach der E-Mail-Adresse suchen, vermeiden Sie es, bereits registrierte Kontakte doppelt anzulegen.
• Darfli- und Differenzialupdates: Es gibt einen Endpunkt, mit dem Sie für einen einzelnen Kontakt gleichzeitig Listen hinzufügen/entfernen, Tags verwalten und Felder aktualisieren können.
• Export und Ereignisabruf: Sie können Kontakte exportieren und den Ereignisverlauf für einzelne Kontakte abrufen.

Listen verwalten

Sie können Listen über die API erstellen, umbenennen, duplizieren, zusammenführen und löschen. Das ist nützlich, wenn Ihr CRM oder E-Commerce-Tool die maßgebliche Datenquelle dafür ist, wie Kundengruppen gebildet werden. So kann beispielsweise das externe System festlegen, wer „3 oder mehr Käufe getätigt hat“ oder „den Gold-Mitgliedschaftsstatus besitzt“, und dies automatisch in Benchmark-Listen spiegeln.

Beachten Sie, dass beim Zusammenführen eine neue Liste erstellt wird, während die Ursprungslisten erhalten bleiben. Doppelte Kontakte werden dabei automatisch bereinigt.

Kampagnen erstellen und konfigurieren

Über die API lassen sich Kampagnenname, Betreff, Vorschmtext, Absendername, Absender- und Antwortadresse, Empfängerliste, HTML-Inhalt und mehr festlegen und als Entwurf anlegen. Auch das Duplizieren einer bestehenden Kampagne ist möglich – das Duplikat wird dabei unabhängig vom Status des Originals immer als Entwurf angelegt.

Berichte abrufen

Folgende fünf Informationsarten lassen sich abrufen:

• Dashboard-Übersicht (letzte 1 bis 90 Tage, inklusive prozentualer Veränderung zum Vorzeitraum)
• Allgemeine Zustellungsleistung (gesendet, zugestellt, Öffnungen, Klicks, Bounces, Abmeldungen, Beschwerden)
• Zeitreihendaten der Zustellungsleistung (praktisch für Diagramme)
• Berichte für einzelne Kampagnen (einschließlich Klicks pro Link)
• Engagement-Trends für einzelne Kampagnen

Wenn Sie diese Daten in ein BI-Tool oder ein eigenes Dashboard einspeisen, entfällt das lästige „Kopieren von Öffnungsraten in Präsentationen“.

Absenderdomains überprüfen

Sie können den Authentifizierungsstatus privater Absenderdomains auslesen. Das ist hilfreich, wenn Sie die Zustellbarkeit auf einem separaten Dashboard überwachen oder ein anderes System darüber informieren möchten, dass „diese Domain jetzt versandbereit ist“.

Kontoinformationen abrufen

Mit GET /api/account lassen sich grundlegende Informationen wie Stadt, Land, Länderode, Währungscode und Zeitzone des Kontos abrufen. Dies können Sie nutzen, um vor dem Aufruf anderer Endpunkte zu prüfen, ob Ihr API-Schlüssel funktioniert, oder um bei Berichten die passende Zeitzone anzuwenden. Beachten Sie, dass der in der Antwort enthaltene Schlüssel unlayerKey ein geheimer Schlüssel (ein SHA256-Hash) für die Unlayer-Integration ist. Achten Sie darauf, diesen nicht in Logs oder auf dem Bildschirm preiszugeben.

Was die API nicht kann (was in der Benchmark Email Oberfläche bleibt)

Die API ist nicht universell einsetzbar; bestimmte Vorgänge wurden absichtlich ausgespart, um einen sicheren Versand zu gewährleisten.

Mit anderen Worten ist das System so konzipiert, dass Aktionen, die einen versehentlichen E-Mail-Versand auslösen könnten, nicht über einen API-Schlüssel ausgeführt werden können. Der vorgesehene Workflow sieht vor, Kampagnenentwürfe über die API vorzubereiten und die finale Prüfung sowie das Absenden von einer Person manuell ausführen zu lassen.

Nutzungseinschränkungen, Rate Limits und Preise

Preise und Anzahl der API-Schlüssel

• Die API selbst ist in allen Tarifen kostenlos
• Im kostenlosen Tarif sind 2 aktive API-Schlüssel erlaubt, im Pro-Tarif bis zu 10 (bei Bedarf an mehr Schlüsseln wenden Sie sich an den Vertrieb)
• Die offizielle Empfehlung lautet: „Erstellen Sie für jede Integration einen eigenen Schlüssel.“ Sie können den Bereich (die Berechtigungen) für jeden Schlüssel einschränken und sie bei Nichtgebrauch einzeln deaktivieren.

Rate Limits und monatliches Kontingent

Laut der Entwicklerdokumentation gelten folgende Limits:

Beispiel: Bei einem Tarif mit einem hypothetischen Kontaktlimit von 1.000 liegt der Richtwert im kostenlosen Tarif bei 10.000 Anfragen pro Monat und in kostenpflichtigen Tarifen bei 100.000 Anfragen pro Monat (dies dient nur als Rechenbeispiel; prüfen Sie die tatsächlichen Zahlen Ihres gebuchten Tarifs).

Wenn Sie ein Limit überschreiten, erhalten Sie den Fehler 429 Too Many Requests, und der Header Retry-After zeigt die Wartezeit in Sekunden an. Die Antwort enthält zudem Header wie X-RateLimit-Remaining (Verbleibende Anfragen für die Stunde) und X-Monthly-Remaining (Verbleibende Anfragen für den Monat), sodass Sie Ihre Verarbeitung anhand der Restkapazitäten steuern können.

Wenn Sie außerdem wiederholt einen ungültigen API-Schlüssel verwenden, wird Ihre IP-Adresse vorübergehend gesperrt. Sollten Sie wiederholt den Fehler 401 erhalten, überprüfen Sie lieber den Schlüssel, anstatt unzählige erneute Versuche zu starten.

Weitere Bedingungen

• Nur Nutzer mit Inhaber-Berechtigungen (Owner) können API-Schlüssel erstellen und verwalten
• Ein Schlüssel kann nur verwendet werden, solange sich das Konto im Status „Open“ oder „Pending Cancel“ befindet (bei Zahlungsverzug oder Kontosperrung erhalten Sie 403)
• Bei jeder Anfrage ist ein User-Agent-Header erforderlich (wird weiter unten beschrieben)

Vom API-Schlüssel zur ersten Anfrage

1. Einen API-Schlüssel erstellen

1. Melden Sie sich mit dem Inhaber-Konto bei Benchmark Email an
2. Öffnen Sie Einstellungen > API-Schlüssel (Settings > API Keys)
3. Klicken Sie auf API-Schlüssel erstellen (Create API Key)
4. Vergeben Sie einen aussagekräftigen Namen (z. B. Sheets Sync) und wählen Sie nur die Scopes aus, die Sie tatsächlich benötigen
5. Legen Sie bei Bedarf ein Ablaufdatum fest (ohne Angabe läuft der Schlüssel nie ab)
6. Kopieren Sie den nach der Erstellung angezeigten Schlüssel sofort und bewahren Sie ihn sicher auf

Der Schlüssel wird nur einmal bei der Erstellung angezeigt. Sollten Sie ihn verlieren, können Sie ihn über die API-Schlüssel-Ansicht neu generieren, wodurch der alte Schlüssel jedoch ungültig wird.

Ein API-Schlüssel besteht aus bme_ + einem 2-stelligen Ländercode (wie us, jp oder eu) + einer 43-stelligen Zufallszeichenfolge, insgesamt 50 Zeichen.

2. Die Basis-URL ermitteln

Die Basis-URL unterscheidet sich je nach Region und Cluster Ihres Kontos und hat das Format https://api-{region}-{cluster}.benchmarkemail.io (z. B. https://api-us-west-2-a.benchmarkemail.io). Ihre individuelle Basis-URL wird Ihnen in den Einstellungen unter API-Schlüssel angezeigt – verwenden Sie genau diese.

3. Die erste Anfrage senden

curl -H "X-API-Key: bme_your-api-key-here" \
  -H "User-Agent: MyIntegration/1.0" \
  "<your-api-base-url>/api/contact-structure"

Wenn die Kontaktstruktur (die Definitionen der benutzerdefierten Felder) als JSON zurückgegeben wird, war Ihre Anfrage erfolgreich. Erhalten Sie stattdessen 401 oder 403, überprüfen Sie den Schlüssel, die Scopes sowie den Kontostatus.

Sollten Sie einen 403-Fehler erhalten, der HTML statt JSON zurückgibt, liegt es höchstwahrscheinlich daran, dass der Header User-Agent nicht gesendet wird. Der Grund dafür ist, dass der Schutzmechanismus von Benchmark Email Anfragen ohne User-Agent abweist. Während cURL und Standardbibliotheken gängiger Programmiersprachen diesen automatisch hinzufügen, muss er beispielsweise bei PHPs cURL-Erweiterung explizit gesetzt werden.

Hinweis: Das cURL-Beispiel auf der Marketing-Einführungsseite (das Format, bei dem list_id an /v1/contacts übergeben wird) und die Endpunkte in der Entwicklerdokumentation (das Format mit contactStructureId und den Feldern _id an /api/contact) unterscheiden sich in ihrer Schreibweise. Halten Sie sich bei der Implementierung unbedingt an die Entwicklerdokumentation (developers.benchmarkemail.io).

Funktionsweise der Scopes

Berechtigungen (Scopes) werden einem API-Schlüssel im Format {resource}:{access type} zugewiesen.

Drei Punkte sind dabei besonders wichtig:

• Write schließt Read ein: Mit contacts:write können Sie Kontakte auch auslesen
• Prinzip der minimalen Rechte: Teilen Sie Ihre Schlüssel auf – verwenden Sie beispielsweise nur reports:read für ein Reporting-Dashboard und nur contacts:write für die Kontaktsynchronisation aus einer Tabelle
• Read reicht für die Suche: Die Kontaktsuche erfolgt per POST, erfordert jedoch lediglich den Scope contacts:read

Konkrete Anwendungsfälle

Im Folgenden betrachte ich – basierend auf den Spezifikationen der offiziellen Dokumentation – Integrationsbeispiele, die echten Nutzen bieten.

Hinweis: Der folgende Code wurde gemäß den Spezifikationen der offiziellen Dokumentation verfasst. Bevor Sie ihn auf Ihre Live-Listen anwenden, testen Sie die Funktionalität stets mit einer Testliste oder einer geringen Datenmenge.

Beispiel 1: Kontakte von Google Sheets mit Benchmark Email synchronisieren

Nehmen wir an, Sie sammeln Anmeldungen für Seminare oder Umfragen in Google Sheets. Sie möchten nur die neu hinzugefügten Zeilen in einer Benchmark Email-Liste registrieren und vermeiden, dass bereits vorhandene E-Mail-Adressen doppelt angelegt werden.

Vorbereitung

1. Erstellen Sie einen API-Schlüssel mit dem Scope contacts:write
2. Ermitteln Sie über GET /api/contact-structure die _id der Kontaktstruktur sowie die _id der Felder für „Vorname“ (First Name) und „Nachname“ (Last Name)
3. Notieren Sie sich die _id der Ziel-Liste (diese können Sie mit GET /api/contact-structure/{structure ID}/lists/all abrufen)
4. Nutzen Sie die erste Zeile der Tabelle als Kopfzeile: Spalte A = E-Mail, Spalte B = Vorname, Spalte C = Nachname, Spalte D = Synchronisationsergebnis
5. Speichern Sie den API-Schlüssel und die IDs in den Skripteigenschaften von Google Apps Script (vermeiden Sie Hardcoding im Quellcode)

Google Apps Script Code

// ===== Settings (saved in script properties) =====
const P = PropertiesService.getScriptProperties();
const BASE_URL = P.getProperty('BME_BASE_URL');           // e.g. https://api-us-west-2-a.benchmarkemail.io
const API_KEY = P.getProperty('BME_API_KEY');             // bme_us_...
const STRUCTURE_ID = P.getProperty('BME_STRUCTURE_ID');   // _id of the contact structure
const LAST_NAME_ID = P.getProperty('BME_LAST_NAME_FIELD_ID');
const FIRST_NAME_ID = P.getProperty('BME_FIRST_NAME_FIELD_ID');
const LIST_ID = P.getProperty('BME_LIST_ID');

// ===== Common API call =====
function api_(method, path, body, retry) {
  retry = retry || 0;
  const res = UrlFetchApp.fetch(BASE_URL + path, {
    method: method,
    contentType: 'application/json',
    headers: { 'X-API-Key': API_KEY, 'User-Agent': 'SheetsToBenchmark/1.0' },
    payload: body ? JSON.stringify(body) : undefined,
    muteHttpExceptions: true,
  });
  const code = res.getResponseCode();
  if (code === 429 && retry < 3) {          // Rate limit: wait, then retry
    Utilities.sleep(60 * 1000);
    return api_(method, path, body, retry + 1);
  }
  if (code >= 400) throw new Error(code + ' ' + res.getContentText());
  const text = res.getContentText();
  return text ? JSON.parse(text) : null;
}

// ===== Duplicate check by email address =====
function emailExists_(email) {
  const r = api_('post', '/api/contact/search', {
    contactStructureId: STRUCTURE_ID,
    page: 1,
    pageSize: 1,
    source: ['_id'],
    contactSpecification: {
      filters: [{ criterias: [{ columnToFilter: 'KEY', operator: 'EQ', values: [email] }] }],
    },
  });
  return r.totalRecords > 0;
}

// ===== Register only unsynced rows =====
function syncNewRows() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Applicants');
  const rows = sheet.getDataRange().getValues();

  for (let i = 1; i < rows.length; i++) {
    const email = String(rows[i][0]).trim();
    const firstName = rows[i][1];
    const lastName = rows[i][2];
    const synced = rows[i][3];
    if (!email || synced) continue;       // Skip empty and already-synced rows

    let result;
    if (emailExists_(email)) {
      result = 'Skipped (already registered)';
    } else {
      api_('post', '/api/contact', {
        key: email,
        contactStructureId: STRUCTURE_ID,
        fields: [
          { _id: LAST_NAME_ID, value: lastName },
          { _id: FIRST_NAME_ID, value: firstName },
        ],
        lists: [{ _id: LIST_ID }],
      });
      result = 'Synced ' + new Date().toLocaleString();
    }
    sheet.getRange(i + 1, 4).setValue(result);
    Utilities.sleep(300);                  // Avoid back-to-back requests
  }
}

Wenn Sie nun die Funktion syncNewRows über einen zeitgesteuerten Trigger in Apps Script (z. B. „stündlich“ oder „jeden Morgen“) ausführen lassen, werden neue Zeilen in der Tabelle automatisch in Ihre Benchmark Email-Liste übertragen. Handelt es sich um die Antworttabelle eines Google-Formulars, können Sie alternativ auch den Auslöser „Bei Formularabsendung“ (On Form Submit) verwenden.

Jede Zeile erfordert maximal 2 Anfragen (Suche + Erstellen), weshalb Sie das Limit von 3.600 Anfragen pro Stunde problemlos einhalten.

Beispiel 2: Zustellungsergebnisse automatisch in Google Sheets schreiben

Ein weiteres Beispiel bildet den umgekehrten Weg ab: Die Ergebnisse gesendeter Kampagnen werden automatisch in eine Tabelle kompiliert. Die Kampagnenlisten-API (GET /api/email/campaign) gibt auch Statistiken zu gesendeten Kampagnen aus (Öffnungen, Klicks, Öffnungsrate usw.). Sie können die Hilfsfunktion api_ aus dem vorherigen Beispiel direkt wiederverwenden.

Dies funktioniert mit einem Schlüssel, der über den Scope campaigns:read verfügt.

function exportCampaignStats() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('Delivery Report') || ss.insertSheet('Delivery Report');

  const res = api_('get', '/api/email/campaign?page=1&size=25&statuses=sent&sort=scheduledAt:desc');

  const header = ['Campaign name', 'Subject', 'Sent at', 'Sent', 'Delivered',
                  'Opens (unique)', 'Open rate (%)', 'Clicks (unique)', 'Click rate (%)'];
  const rows = res.records.map(function (c) {
    const s = c.stats || {};
    return [
      c.name, c.subject, c.scheduledAt,
      s.sent, s.delivered,
      s.opens && s.opens.unique, s.opens && s.opens.rate,
      s.clicks && s.clicks.unique, s.clicks && s.clicks.rate,
    ];
  });

  sheet.clearContents();
  sheet.getRange(1, 1, 1, header.length).setValues([header]);
  if (rows.length) sheet.getRange(2, 1, rows.length, header.length).setValues(rows);
}

Wenn Sie dieses Skript über einen täglichen Morgen-Trigger ausführen lassen, stehen Ihnen die neuesten Ergebnisse direkt beim Öffnen der Tabelle zur Verfügung. Von dort aus können Sie automatisierte Wöchentlich-Berichte erstellen, indem Sie die Standarddiagramme von Google Sheets nutzen oder eine Verbindung zu Looker Studio herstellen.

Für detailliertere Analysen lässt sich zudem die Berichte-API heranziehen:

• GET /api/reports/dashboard?pastDays=30&timezone=America/New_York: Übersicht der letzten 30 Tage (inkl. prozentualer Veränderung zum Vormonat)
• GET /api/reports/email/{campaign ID}: Klicks pro Link für eine bestimmte Kampagne
• GET /api/reports/email/{campaign ID}/engagement?period=week: Trend von Öffnungen und Klicks in der ersten Woche nach dem Versand

Wenn Sie timezone auf Ihre eigene Zeitzone (z. B. America/New_York) einstellen, werden die Daten exakt in dieser Zeitzone aggregiert, was für regionale Reports sehr praktisch ist.

Beispiel 3: Kunden aus Onlineshop oder Buchungsformular automatisch zur Liste hinzufügen (n8n, Zapier & Co.)

Benchmark Email verfügt derzeit über kein integriertes No-Code-Workflow-Tool. In der offiziellen Dokumentation wird jedoch darauf hingewiesen, dass man Workflows über Tools wie Zapier und n8n per API automatisieren kann. Wenn Sie einen Knoten verwenden, der HTTP-Anfragen senden kann (z. B. den HTTP-Request-Knoten in n8n oder Webhooks in Zapier), gelingt die Integration nahezu ohne Programmieraufwand.

Ein typischer Ablauf sieht so aus:

1. Auslöser (Trigger): Eine Bestellung geht im Shop ein / ein Buchungsformular wird abgesendet / ein Google-Formular wird ausgefüllt
2. Suche: Prüfen Sie mit POST /api/contact/search, ob die E-Mail-Adresse bereits registriert ist
3. Verzweigung (Branch)
   • Nicht registriert → Erstellen Sie den Kontakt mit POST /api/contact und fügen Sie ihn einer Liste hinzu
   • Registriert → Nutzen Sie den Endpunkt für Differenzialupdates, um Listen zuzuordnen, Tags zu vergeben oder Felder zu aktualisieren
4. Benachrichtigung: Informieren Sie bei Bedarf Slack oder Microsoft Teams über die Registrierung eines neuen Kontakts

Wenn Sie bei der Suche nach FIELD_ID filtern, können Sie auch Bedingungen prüfen wie „Nur Personen mit Gold-Mitgliedschaftsstatus“. So halten Sie Ihre Benchmark Email-Listen automatisch aktuell, während die führenden Kundendaten im E-Commerce-System oder CRM verbleiben.

Beispiel 4: Newsletter des Vormonats duplizieren, um den Entwurf für diesen Monat zu erstellen

Bei wiederkehrenden Formaten wie einem monatlichen Newsletter, bei dem im Wesentlichen dasselbe Design verwendet wird, bietet es sich an, einen Entwurf durch Duplizieren einer früheren Kampagne vorzubereiten.

# 1. Duplicate last month's campaign to create this month's draft
curl -X POST "<your-api-base-url>/api/email/campaign/{last month's campaign ID}/duplicate" \
  -H "X-API-Key: $BENCHMARK_KEY" \
  -H "User-Agent: MonthlyNewsletter/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "November 2026 Newsletter" }'

# 2. Update the subject, preview text, and destination list (__v is the value you just retrieved)
curl -X PATCH "<your-api-base-url>/api/email/campaign/{new campaign ID}" \
  -H "X-API-Key: $BENCHMARK_KEY" \
  -H "User-Agent: MonthlyNewsletter/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "[November Issue] This Month'"'"'s Announcements",
    "previewText": "A roundup of new features and use cases",
    "lists": ["{destination list ID}"],
    "__v": 0
  }'

Öffnen Sie im Anschluss den Entwurf in der Benutzeroberfläche von Benchmark Email, passen Sie den Text an, prüfen Sie den Inhalt und versenden Sie ihn. Wenn Sie die Aufgaben so aufteilen, dass die API das „Vorbereiten des Entwurfs“ übernimmt und ein Mensch die „endgültige Prüfung und den Versand“ durchführt, arbeiten Sie effizient und sicher.

Beispiel 5: Die Implementierung einem KI-Coding-Assistenten überlassen

Die offizielle Entwicklerdokumentation stellt auch Ressourcen für KI-Programmierassistenten bereit:

• llms.txt: Ein Inhaltsverzeichnis aller Dokumentationsseiten
• llms-full.txt: Den vollständigen Text der gesamten Dokumentation in einer einzigen Datei
• SKILL.md: Einen Agenten-Leitfaden, der Endpunkte, Entscheidungsrichtlinien und häufige Fehler zusammenfasst

Wenn Sie mit einer KI arbeiten, empfiehlt sich folgende Anweisung: „Lies zuerst SKILL.md, lies dann den Szenario-Leitfaden, der zu meinem Vorhaben passt, und schreibe anschließend den Code.“ Selbst ein Google Apps Script wie in Beispiel 1 lässt sich auf diese Weise im Handumdrehen an Ihre eigenen Anforderungen anpassen, indem Sie der KI die Spezifikationen vorlegen und sie bitten, „den Code an das Spaltenlayout meiner Tabelle anzupassen“.

Wichtige Punkte bei der Implementierung

Hier sind Stolperfallen aus den Szenario-Leitfäden, auf die Sie achten sollten:

• PUT ist ein „vollständiger Ersatz“: Wenn Sie einen Kontakt per PUT aktualisieren, werden alle Felder überschrieben, die Sie nicht explizit im Anfrage-Body angegeben haben. Rufen Sie daher zuerst per GET die neuesten Daten ab, nutzen Sie diese als Basis und ändern Sie nur die gewünschten Felder, bevor Sie die Anfrage absenden.
• Die Versionsnummer __v ist erforderlich: Für PUT-Anfragen sowie für PATCH-Anfragen bei Kampagnen und Listen müssen Sie den per GET ermittelten Wert __v mitsenden. Bei veralteten Werten erhalten Sie einen Fehler (400) vom Typ ConcurrencyError. Rufen Sie die Daten in diesem Fall erneut ab und wiederholen Sie den Vorgang.
• Statuswerte unterscheiden Groß- und Kleinschreibung: Statusangaben wie Active, Inactive und Unsubscribe müssen exakt so übergeben werden; Kleinbuchstaben führen zu einem Fehler. Wenn Sie Inactive festlegen, sind sowohl primary als auch secondary erforderlich.
• Abgemeldete oder gebouncede Kontakte können nicht wiederhergestellt werden: Sobald ein Kontakt den Status Inactive annimmt, kann er über die API nicht mehr auf Active zurückgesetzt werden. Dies ist eine Vorgabe zum Schutz der Compliance – versuchen Sie gar nicht erst, solche Kontakte eigenmächtig zu reaktivieren.
• Duplikate führen zu Fehlern: Wenn dieselbe E-Mail-Adresse bereits in derselben Struktur existiert, erhalten Sie DuplicateFieldError. Prüfen Sie daher vor dem Erstellen per Suche oder reagieren Sie auf den Fehler, indem Sie auf eine Aktualisierung umschalten.
• Der Parameter source in der Suche ist Pflicht: Sie müssen die gewünschten Rückgabefelder als Array angeben (z. B. _id, key und fields). Die Werte berücksichtigen Groß- und Kleinschreibung; ist auch nur ein einziger ungültiger Wert enthalten, wird die gesamte Anfrage abgelehnt.
• Das Abrufen von Kontaktlisten bietet keine Seitennummerierung (Paging): GET /api/contact gibt alle Datensätze auf einmal aus. Bei Konten mit sehr vielen Einträgen ist die Such-API, die Paging unterstützt, die sicherere Wahl.
• Die Absenderadresse muss von einer authentifizierten Domain stammen: Die Absenderadresse einer Kampagne (from) muss zwingend zu einer authentifizierten Absenderdomain gehören.
• Verwaltung von Schlüsseln: Nutzen Sie immer Umgebungsvariablen oder Skripteigenschaften. Hardcodieren Sie Schlüssel niemals im Quellcode oder in Tabellenzellen. Sollten Sie einen Leak vermuten, deaktivieren Sie den Schlüssel und generieren Sie sofort einen neuen.

Vor- und Nachteile der Benchmark Email API

Für wen geeignet und für wen nicht

Für wen es geeignet ist

• Ihre Kundendaten liegen verstreut an verschiedenen Orten (Onlineshop, Buchungssystem, CRM, Tabellen) und Sie möchten Zeit beim manuellen Datenabgleich sparen
• Sie haben einen Entwickler im Team oder können die Implementierung einem KI-Coding-Tool überlassen
• Sie möchten Zustellungsergebnisse in einem eigenen Dashboard oder BI-Tool auswerten
• Sie versenden jeden Monat E-Mails im nahezu gleichen Format und möchten lediglich die Erstellung der Entwürfe automatisieren

Für wen es nicht geeignet ist

• Ihre Abläufe funktionieren komplett innerhalb der Benchmark Email-Oberfläche und Sie benötigen schlicht keine externen Verknüpfungen
• Sie suchen nach einer rein visuellen No-Code-Integration per Mausklick (derzeit erfordert dies die Einbindung von HTTP-Anfragen in Tools wie Zapier)
• Sie möchten den E-Mail-Versand selbst direkt aus der API heraus starten (für Transaktions-E-Mail-Anwendungsfälle ist das Tool nicht ausgelegt)

Häufig gestellte Fragen (FAQ)

F. Kann ich die API im kostenlosen Tarif von Benchmark Email nutzen?

Ja. Die API ist in allen Tarifen kostenlos enthalten. Im kostenlosen Tarif können Sie bis zu 2 aktive API-Schlüssel erstellen.

F. Kann ich die API ohne Programmierkenntnisse nutzen?

Sie müssen Code für die Integration schreiben – oder generieren lassen. Selbst wenn Sie selbst nicht programmieren können, lässt sich dies über einen Entwickler oder einen KI-Coding-Assistenten problemlos realisieren.

F. Kann ich E-Mails über die API versenden?

Nicht direkt. Das Erstellen, Konfigurieren und Duplizieren von Kampagnen ist über die API möglich, aber das Planen und Absenden muss in der Benchmark Email-Benutzeroberfläche erfolgen.

F. Wo kann ich einen API-Schlüssel erstellen?

Mit einem Inhaber-Konto (Owner) können Sie unter Einstellungen > API-Schlüssel (Settings > API Keys) einen Schlüssel anlegen. Da der Schlüssel nur einmal bei der Erstellung angezeigt wird, sollten Sie ihn unbedingt sofort sicher notieren.

F. Wie lauten die Rate Limits?

Laut der Entwicklerdokumentation liegt das Limit bei 3.600 Anfragen pro Stunde und Konto (als Summe über alle Schlüssel hinweg). Das monatliche Kontingent entspricht dem 10-fachen (kostenlos) bzw. 100-fachen (kostenpflichtig) des Kontaktlimits. Da sich diese Zahlen ändern können, prüfen Sie die aktuellen Details im Abschnitt „Rate Limits“ der offiziellen Dokumentation.

F. Kann ich eine Integration mit Google Sheets einrichten?

Es gibt zwar keinen offiziellen Konnektor, aber Sie können die API über Google Apps Script mit Hilfe von UrlFetchApp ansprechen. Wie in den Beispielen 1 und 2 dieses Artikels gezeigt, lassen sich damit Kontakte aus einer Tabelle registrieren und Zustellungsergebnisse exportieren.

Fazit

Die Benchmark Email API ist eine in allen Tarifen kostenlose Schnittstelle, um Kontakte, Listen, Kampagnen, Berichte und Absenderdomains mit externen Tools zu verknüpfen.

• Sie können damit die manuelle Datenpflege automatisieren – etwa das Synchronisieren von Kontakten, Suchen, Duplikatsprüfungen, Listenmanagement und das Abrufen von Berichten.
• Auf der anderen Seite lassen sich Versand, Terminierung und finales Design nicht über die API steuern – aus Sicherheitsgründen bleibt die Kontrolle in der Benutzeroberfläche bestehen.
• Für die Nutzung benötigen Sie Unterstützung durch einen Entwickler oder eine KI. Da Benchmark Email jedoch Ressourcen wie llms.txt und SKILL.md bereitstellt, fällt die Hürde bei Einsatz von KI überraschend gering aus.
• Mittels Google Sheets und Google Apps Script können Sie Anmeldelisten automatisch registrieren und Zustellungsergebnisse automatisiert auswerten.

Beginnen Sie am besten damit, im kostenlosen Tarif einen API-Schlüssel zu erstellen, GET /api/contact-structure aufzurufen und die Struktur Ihres eigenen Kontos zu überprüfen. Im Anschluss empfiehlt es sich, genau jene Aufgabe zu automatisieren, die bisher den größten manuellen Aufwand erfordert (wie etwa die Tabellensynchronisation).

Referenzlinks

• Benchmark Email API (offizielle Funktionsseite)