API-Dokumentation

Öffentliche REST-API: Authentifizierung, Endpunkte, Fehlerkatalog, Sandbox-Schlüssel.

Authentifizierung

Senden Sie mit jeder Anfrage den Header Authorization: Bearer <Schlüssel>. Schlüssel erzeugen Sie in Ihrer angemeldeten Sitzung (Einstellungen → API-Schlüssel). Die API selbst erzeugt keine Schlüssel, ein gestohlener Schlüssel kann sich also nicht selbst vermehren.

curl https://your-domain.com/api/v1/verify \
  -H "Authorization: Bearer cl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"name@example.com"}'

Sandbox-Schlüssel

Ein Schlüssel mit dem Präfix cl_test_ erreicht den Worker nie und verbraucht keine Credits. Senden Sie die Testadressen, um jeden Status auszuprobieren: ok@sandbox.test, invalid@sandbox.test, catch_all@sandbox.test, disposable@sandbox.test, role@sandbox.test, unknown@sandbox.test. Jede andere Adresse liefert unknown. Bleibt der Testschlüssel versehentlich live, wird keine echte Adresse freigegeben.

Endpunkte

Sieben Endpunkte, alle außerhalb des [locale]-Präfixes, wie diese Seite:

POST/api/v1/verifyEinzelne E-Mail prüfen, sofortige Antwort.
POST/api/v1/listsMassenliste aus einem JSON-Array erstellen.
GET/api/v1/lists/:idStatus einer Liste abrufen.
GET/api/v1/lists/:id/resultsErgebnisse einer Liste abrufen.
DELETE/api/v1/lists/:idListe dauerhaft löschen (DSGVO).
GET/api/v1/creditsVerbleibende Credits abrufen.
POST / GET / DELETE/api/v1/webhooksWebhook-Endpunkt registrieren, auflisten oder entfernen.

Fehlerkatalog

Jeder Fehler hat dasselbe Format: { error: { code, message, request_id } }. Der code ist einer der folgenden festen Werte.

unauthorized401Schlüssel fehlt oder ist ungültig.
forbidden403Der Schlüssel darf diese Aktion nicht ausführen (z. B. Credit-Abfrage mit einem veröffentlichbaren Schlüssel).
not_found404Der Datensatz existiert nicht oder gehört Ihnen nicht. In beiden Fällen lautet die Antwort 404, nie 403.
invalid_request400Der Body entspricht nicht dem erwarteten Schema.
insufficient_credits402Credits reichen nicht aus.
rate_limited429Anfragelimit überschritten. Warten Sie die im Retry-After-Header genannte Zeit ab.
too_large413Body-Größe überschreitet das Limit.
internal500Serverfehler, erneut versuchen.

Idempotenz

Senden Sie einen Idempotency-Key-Header, liefert eine zweite Anfrage mit demselben Schlüssel unverändert die erste erfolgreiche Antwort. Fehler werden nicht gespeichert: Nach einem 4xx oder 5xx führt derselbe Schlüssel die Anfrage erneut aus. Derselbe Schlüssel mit einem anderen Body liefert 400. Läuft die erste Anfrage noch, erhält eine zweite 429 mit Retry-After: 1; versuchen Sie es erneut, dann kommt die erste Antwort. Die gespeicherte Antwort enthält nie eine E-Mail-Adresse.

Anfragelimit

Derzeit 60 Anfragen pro Minute und Schlüssel, gemessen in einem gleitenden 60-Sekunden-Fenster. Darüber hinaus erhalten Sie 429 mit einem Retry-After-Header.

Ein Publishable-Schlüssel (Browser) startet außerdem standardmäßig höchstens 500 Prüfungen pro 24 Stunden; Sie ändern das auf der Seite API-Schlüssel. Darüber hinaus erhalten Anfragen 429 und kosten kein Guthaben.

Fertige Integrationen

Sehen Sie sich das an, bevor Sie die API direkt aufrufen:

  • Mailchimp-Synchronisierung: Liste abrufen, prüfen, Tags zurückschreiben (Einstellungen → Integrationen).
  • Webhook: ein signierter POST, sobald ein Massenauftrag abgeschlossen ist (X-Clearlist-Signature).
Dokumentation der E-Mail-Verifizierungs-API