API

Eine REST-API über HTTPS. Alles ist JSON, jedes Feld ist snake_case, und die Basis ist https://listcheckup.com. Es gibt kein SDK zu installieren und nichts abzuwarten — erstellen Sie einen Schlüssel, und die beiden Befehle unten funktionieren.

Authentifizierung

Jede Anfrage trägt einen API-Schlüssel, erstellt in Ihrem Dashboard. Schlüssel beginnen mit lck_live_, können ein Ablaufdatum erhalten und lassen sich jederzeit widerrufen.

curl "https://listcheckup.com/v1/me" \
  -H "Authorization: Bearer lck_live_..."

GET /v1/me antwortet mit dem Konto, zu dem der Schlüssel gehört, und dessen Guthaben — der schnellste Weg zu bestätigen, dass ein Schlüssel funktioniert:

{ "email": "[email protected]", "credits": 24600 }

Ohne Schlüssel, oder mit einem widerrufenen oder abgelaufenen, antwortet jeder Endpunkt mit 401 und sagt, welcher dieser Fälle es war — ein widerrufener Schlüssel und ein Tippfehler verlangen unterschiedliche Korrekturen.

Rate Limit

120 Anfragen zum Start, aufgefüllt mit 60 pro Minute, je Schlüssel. Das ist eine Obergrenze für Anfragen, nicht für Adressen: Eine Liste mit einer halben Million Adressen ist eine einzige Anfrage. Wer sie überschreitet, erhält 429 — Warten ist die Lösung.

Eine Adresse prüfen

Die Antwort kommt direkt in der Response. Für die Momente, in denen jemand wartet — ein Anmeldeformular, ein Checkout — nicht für eine Liste, die Sie bereits haben.

curl "https://listcheckup.com/v1/[email protected]" \
  -H "Authorization: Bearer lck_live_..."

Es gibt auch POST /v1/verify mit { "email": "..." } im Body, falls ein Query-String unpraktisch ist. Beide liefern dasselbe:

{
  "email": "[email protected]",
  "normalized_email": "[email protected]",
  "local_part": "someone",
  "domain": "example.com",
  "status": "valid",
  "reason": "mailbox_accepted",
  "confidence": 95,
  "duration_ms": 412
}

status ist einer von fünf Werten, und confidence gibt mit 0–100 an, wie belastbar dieser Status ist. Ein Catch-all erhält einen niedrigen Wert, obwohl der Server die Adresse angenommen hat — denn dort beweist die Annahme nichts.

status	Bedeutung
valid	Das Postfach existiert und kann Mail empfangen.
invalid	Kann keine Mail empfangen. Entfernen Sie die Adresse.
risky	Funktioniert, ist aber eine Wegwerfadresse oder ein geteiltes Postfach, keine Person.
catch_all	Die Domain nimmt jede Adresse an — ob genau diese existiert, kann daher niemand sagen.
unknown	Der Mailserver wollte nicht antworten. Eine Aussage über dessen Richtlinie, nicht über die Adresse.

Berechnet wird nur eine Antwort. catch_all und unknown kosten nichts, denn die Arbeit wurde geleistet und der Mailserver hat die Auskunft verweigert — dafür Credits zu nehmen hieße, Ihnen in Rechnung zu stellen, dass wir es nicht herausfinden konnten.

Eine Liste prüfen

Vier Aufrufe: anlegen, starten, nachsehen, abholen.

1. Anlegen

Adressen als JSON, kein Datei-Upload — Sie halten sie ohnehin als Strings, und ein Multipart-Body nur, um Strings zu senden, wäre Arbeit für nichts.

curl -X POST "https://listcheckup.com/v1/lists" \
  -H "Authorization: Bearer lck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "march-subscribers", "emails": ["[email protected]", "[email protected]"]}'

Noch wird nichts berechnet. Die Antwort ist eine Listenübersicht mit dem Preis, sodass Sie entscheiden können, bevor irgendetwas ausgegeben wird:

{
  "id": "7f3c1d20-9a4b-4c8e-8f21-5b6d7e8a9c04",
  "name": "march-subscribers",
  "status": "awaiting_confirmation",
  "addresses": 24600,
  "duplicates": 1020,
  "not_addresses": 180,
  "unique": 23580,
  "excluded": 0,
  "price": 23400,
  "checked": 0,
  "credits_charged": 0,
  "failure_reason": null,
  "created_at": "2026-03-18T09:12:00+00:00",
  "completed_at": null
}

price ist in Credits angegeben und ist das, was der Start kosten wird. Dubletten werden nur einmal gezählt, und Zeilen, die keine Adressen sind, werden nie berechnet — deshalb liegt der Wert unter addresses.

2. Starten

curl -X POST "https://listcheckup.com/v1/lists/<id>/start" \
  -H "Authorization: Bearer lck_live_..."

Das ist der Aufruf, der Credits ausgibt. 402 bedeutet: Das Guthaben reicht nicht, und es wurde weder etwas berechnet noch gestartet.

3. Wissen, wann sie fertig ist

Registrieren Sie einen Webhook, und wir senden ein POST an Ihren Server, sobald eine Liste fertig ist — signiert, mit erneuten Zustellversuchen, falls Ihre Seite gerade nicht erreichbar ist. Das ist der richtige Weg.

Wer lieber selbst nachfragt: GET /v1/lists/<id> liefert dieselbe Übersicht wie oben, mit fortschreitendem status und checked. Fragen Sie sparsam ab; ein Webhook kostet Sie gar keine Anfragen.

status	Bedeutung
uploaded	Angenommen, noch nicht gelesen.
reading	Wird gezählt. price ist null, bis dieser Schritt abgeschlossen ist.
awaiting_confirmation	Gezählt und bepreist. Berechnet wird nichts, bis Sie die Liste starten.
queued	Gestartet, wartet auf einen Worker.
running	Läuft. checked steigt.
completed	Fertig. Die Ergebnisse liegen bereit.
failed	Abgebrochen. Siehe failure_reason.
cancelled	Von Ihnen abgebrochen. Nicht verbrauchte Credits kommen zurück.

4. Ergebnisse abholen

curl "https://listcheckup.com/v1/lists/<id>/results?limit=500&skip=0" \
  -H "Authorization: Bearer lck_live_..."

limit ist standardmäßig 500 und bei 2.000 gedeckelt; blättern Sie mit skip. Mit include=valid,risky grenzen Sie auf die Kategorien ein, die Sie brauchen.

{
  "id": "7f3c1d20-...",
  "status": "completed",
  "total": 24600,
  "offset": 0,
  "returned": 500,
  "results": [
    {
      "row": 1,
      "email": "[email protected]",
      "status": "valid",
      "confidence": 95,
      "reason": "mailbox_accepted",
      "billable": true,
      "duplicate_of_row": null
    }
  ]
}

row ist die Position in der Liste, die Sie eingereicht haben — so lassen sich die Ergebnisse Ihren eigenen Datensätzen zuordnen, ohne über die Adresse abzugleichen.

Löschen

DELETE /v1/lists/<id> entfernt eine Liste samt ihren Ergebnissen. Was für eine nie gestartete Liste nicht ausgegeben wurde, kommt zurück.

Webhooks

Tragen Sie im Dashboard einen Endpunkt ein, und wir senden ein signiertes POST, sobald eine Liste fertig ist:

{
  "event": "list.finished",
  "occurred_at": "2026-03-18T09:41:00+00:00",
  "list": {
    "id": "7f3c1d20-...",
    "name": "march-subscribers",
    "checked": 24600,
    "safe_to_send": 12000,
    "to_remove": 7400,
    "uncertain": 3100
  }
}

Antworten Sie mit einem beliebigen 2xx. Bei allem anderen versuchen wir es erneut, sechsmal über rund einen Tag verteilt. Jede Anfrage trägt eine HMAC-SHA256-Signatur, die Sie mit Ihrem Signing Secret prüfen; das genaue Schema, samt durchgerechnetem Beispiel, steht neben dem Secret, wenn Sie den Endpunkt anlegen.

Slack funktioniert ganz ohne das. Fügen Sie statt Ihrer eigenen URL eine Slack-Incoming-Webhook-URL ein, und wir senden statt des JSON oben eine Nachricht, die Slack anzeigen kann — nichts zu schreiben, nichts zu hosten. Zustellversuche und das Zustellprotokoll funktionieren genauso.

Aus einem KI-Assistenten nutzen

Es gibt einen MCP-Server unter https://listcheckup.com/mcp. Richten Sie einen Assistenten, der MCP unterstützt — Claude, oder ein Editor wie Cursor — mit demselben API-Schlüssel auf diese URL, und er kann Adressen für Sie prüfen, ohne dass jemand Code schreibt.

Verbinden

Wie auch immer Sie sich verbinden: Der Schlüssel reist stets auf dieselbe Weise, als Authorization: Bearer <key>-Header. Nur wo Sie ihn eintragen, unterscheidet sich.

Claude Code — ein Befehl:

claude mcp add --transport http listcheckup https://listcheckup.com/mcp \
  --header "Authorization: Bearer lck_live_..."

Claude Desktop, Cursor und die meisten anderen Clients — in der Konfigurationsdatei:

{
  "mcpServers": {
    "listcheckup": {
      "url": "https://listcheckup.com/mcp",
      "headers": { "Authorization": "Bearer lck_live_..." }
    }
  }
}

Prüfen, ob die Verbindung steht

Bevor Sie irgendetwas daran anschließen, fragen Sie den Server, was er kann:

curl -X POST "https://listcheckup.com/mcp"   -H "Authorization: Bearer lck_live_..."   -H "Content-Type: application/json"   -H "Accept: application/json, text/event-stream"   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Werden sechs Tools aufgelistet, sind Sie verbunden. "error": "unauthorized" bedeutet, dass der Schlüssel nicht angekommen ist — fast immer fehlt das Wort Bearer mitsamt seinem Leerzeichen, oder der Schlüssel wurde beim Einfügen abgeschnitten. Ein Schlüssel hat rund fünfzig Zeichen und beginnt mit lck_live_.

Was er kann

Tool	Was es tut
check_email	Eine Adresse. Kostet einen Credit, außer die Antwort ist Catch-all oder Unknown.
get_balance	Verbleibende Credits. Kostenlos.
create_list	Eine Liste einreichen und einen Preis erhalten. Berechnet nichts.
start_list	Die Prüfung beginnen. Das ist der Aufruf, der Credits ausgibt.
get_list	Status und Fortschritt. Kostenlos.
get_list_summary	Die Zahlen, sobald sie fertig ist. Kostenlos.

Bepreisen und Starten sind bewusst zwei getrennte Tools: Ein Assistent muss Ihnen zeigen, was eine Liste kosten wird, bevor irgendetwas ausgegeben wird, und Sie können Nein sagen. Kein Tool nimmt ein Konto als Argument entgegen — der Schlüssel im Header entscheidet, wessen Credits verwendet werden, sodass nichts, was ein Assistent liest oder gesagt bekommt, ihn auf das Konto eines anderen lenken kann.

Behandeln Sie den Schlüssel wie ein Passwort

Alles, was ihn besitzt, kann Ihre Credits ausgeben. Er liegt im Klartext in einer Konfigurationsdatei — halten Sie diese Datei also aus gemeinsam genutzten Repositories heraus, und widerrufen Sie den Schlüssel, wenn er irgendwohin gelangt ist, wo er nicht hingehört — der Widerruf wirkt sofort, für die API wie für diesen Server. Geben Sie jeder Maschine ihren eigenen Schlüssel, dann können Sie einen widerrufen, ohne die übrigen zu stören.

Fehler

Jeder Fehler ist JSON mit einem stabilen Code und einem Satz, der für Menschen gedacht ist:

{ "error": "unauthorized", "message": "Provide your API key as 'Authorization: Bearer <key>'." }

Code	Bedeutung
400	In der Anfrage fehlt etwas oder ist falsch. Der Body sagt, was.
401	Kein Schlüssel, oder ein unbekannter, widerrufener oder abgelaufener.
402	Nicht genug Credits. Es wurde weder etwas berechnet noch gestartet.
404	Keine solche Liste auf diesem Konto.
409	Die Liste ist nicht in einem Zustand, in dem das Sinn ergibt — etwa bereits gestartet.
429	Rate Limit erreicht. Warten Sie.

Was die API nicht tut

Die API prüft Adressen, die Sie bereits besitzen. Sie findet, erzeugt oder liefert keine Adressen, und sie sendet nie Mail an die Adressen, die sie prüft — das Gespräch mit jedem Mailserver wird beendet, bevor eine Nachricht existiert. Die Nutzung für gescrapte, gekaufte oder gemietete Listen ist untersagt; siehe zulässige Nutzung.