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/verify | Einzelne E-Mail prüfen, sofortige Antwort. |
| POST | /api/v1/lists | Massenliste aus einem JSON-Array erstellen. |
| GET | /api/v1/lists/:id | Status einer Liste abrufen. |
| GET | /api/v1/lists/:id/results | Ergebnisse einer Liste abrufen. |
| DELETE | /api/v1/lists/:id | Liste dauerhaft löschen (DSGVO). |
| GET | /api/v1/credits | Verbleibende Credits abrufen. |
| POST / GET / DELETE | /api/v1/webhooks | Webhook-Endpunkt registrieren, auflisten oder entfernen. |
Fehlerkatalog
Jeder Fehler hat dasselbe Format: { error: { code, message, request_id } }. Der code ist einer der folgenden festen Werte.
| unauthorized | 401 | Schlüssel fehlt oder ist ungültig. |
| forbidden | 403 | Der Schlüssel darf diese Aktion nicht ausführen (z. B. Credit-Abfrage mit einem veröffentlichbaren Schlüssel). |
| not_found | 404 | Der Datensatz existiert nicht oder gehört Ihnen nicht. In beiden Fällen lautet die Antwort 404, nie 403. |
| invalid_request | 400 | Der Body entspricht nicht dem erwarteten Schema. |
| insufficient_credits | 402 | Credits reichen nicht aus. |
| rate_limited | 429 | Anfragelimit überschritten. Warten Sie die im Retry-After-Header genannte Zeit ab. |
| too_large | 413 | Body-Größe überschreitet das Limit. |
| internal | 500 | Serverfehler, 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).