API-Referenz zur E-Mail-Verifizierung

Jetzt starten

Erstellen Sie unter „API-Schlüssel“ einen Testschlüssel, bewahren Sie ihn auf Ihrem Server auf und setzen Sie FAIRVALID_API_KEY und FAIRVALID_BASE_URL. Testschlüssel funktionieren mit reservierten @example.com-Adressen. Sie lösen keinen Anbieteraufruf aus und verbrauchen keine Credits.

curl -X POST "$FAIRVALID_BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY" \
  -H "Idempotency-Key: my-import-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{"emails":["deliverable@example.com","pending@example.com"]}'

Erstellen Sie für die Produktion einen Live-Key mit dem Scope submit und verwenden Sie /api/v1/jobs oder /api/v1/verifications. Fügen Sie den Scope read hinzu, um Job-Status und Ergebnisse zu lesen.

Ein neuer Job gibt HTTP 202 und eine UUID job_id zurück. Ein passender erneuter Versuch gibt HTTP 200 mit demselben Job zurück. Antworten enthalten version: v1, brand: FairValid und No-Store-Header.

Schlüssel und Ausgabenlimits

Übergeben Sie Authorization: Bearer fv_live_… oder Bearer fv_test_… von einem Server. Vollständige Secrets werden nur einmal angezeigt. Live-Schlüssel können die Scopes submit, read und balance haben. Ein widerrufener Schlüssel stoppt neue Anfragen. Testschlüssel greifen auf ihre eigenen simulierten Aufträge zu.

Das Gesamtlimit eines Live-Schlüssels umfasst bereits abgebuchte Credits sowie Credits, die für angenommene eindeutige Identitäten reserviert sind. Es kann dem Workspace keine Credits hinzufügen. Eine neue Anfrage über dem Limit gibt HTTP 402 key_cap_reached zurück, ohne einen Job oder eine Reservierung zu erstellen. Eine Senkung des Limits blockiert neue Aufträge; bereits angenommene Aufträge laufen weiter.

Live-Aufträge nutzen die Verifizierungswarteschlange und das Credit-Guthaben Ihres Workspace. Schlüsselberechtigungen, Schlüssellimits, Workspace-Zugriff und Verarbeitungslimits gelten weiterhin. Workspace-Credits werden reserviert, sobald Prüfungen zur Verarbeitung angenommen werden; für Ergebnisse gelten dieselben Abrechnungs- und Rückgaberegeln wie im Dashboard.

Während einer betrieblichen Pause kann eine neue Live-Anfrage HTTP 503 live_verification_unavailable zurückgeben, ohne Credits zu reservieren. Versuchen Sie es später mit demselben Idempotency-Key erneut.

Aufträge und Ergebnisse

Methode	Pfad	Zweck
`POST`	`/api/v1/jobs`	Übermitteln Sie 1 bis 5.000 Adressen im JSON-Format, bis zu 2 MiB.
`POST`	`/api/v1/verifications`	Übermitteln Sie eine echte Adresse oder nutzen Sie den ursprünglichen Einzeladressen-Simulator.
`GET`	`/api/v1/jobs/{id}`	Aktuellen Job-Status und Zusammenfassung abrufen.
`GET`	`/api/v1/jobs/{id}/results`	Bis zu 50 Ergebnisse und einen signierten Next-Cursor abrufen.
`POST`	`/api/v1/jobs/{id}/cancel`	Abbruch anfordern; bereits laufende Vorgänge werden möglicherweise noch abgeschlossen.
`GET`	`/api/v1/balance`	Aktuell verfügbare und reservierte Credits des Workspace abrufen.

curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"
curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"

Übergeben Sie next_cursor als Query-Parameter cursor. Er enthält den ursprünglichen Filter und die Suche. Filter sind all, valid, invalid, catch_all, unknown, still_checking und not_checked. Live-Ergebnis- und Guthabenstatus entsprechen dem Dashboard-Snapshot. Der Auftragsstatus kann queued, running, paused, canceling, canceled oder completed sein. Testaufträge liefern deterministische Status: completed, pending, failed oder cancelled.

Fehler und sichere Wiederholungen

Senden Sie bei jeder Job-Übermittlung und jeder Live-Übermittlung einer einzelnen Adresse einen Idempotency-Key aus 8 bis 128 zulässigen Zeichen (Buchstaben, Ziffern, Punkte, Doppelpunkte, Unterstriche oder Bindestriche). Wiederholen Sie die Anfrage bei einer unklaren Antwort mit demselben API-Schlüssel, demselben Idempotency-Key und demselben normalisierten Body. Die Wiederholung ist an den API-Schlüssel gebunden; wenn Sie diese Zugangsdaten ersetzen und erneut übermitteln, kann ein weiterer Durchlauf entstehen. Wird der Idempotency-Key mit geändertem Body wiederverwendet, erhalten Sie HTTP 409 idempotency_conflict. Verwenden Sie nur dann einen neuen Idempotency-Key, wenn Sie bewusst einen neuen Durchlauf starten möchten, der möglicherweise Credits verbraucht.

HTTP 401 bedeutet, dass der Schlüssel fehlt, widerrufen wurde oder nicht die erforderliche Berechtigung hat. HTTP 422 betrifft ungültige Adressen oder Listenlimits. Test-Massenaufträge geben HTTP 429 zurück, wenn pro Workspace mehr als 20 neue Aufträge pro Stunde oder 100 in 30 Tagen erstellt werden; identische Wiederholungen liefern weiterhin den ursprünglichen Auftrag. HTTP 503 bedeutet, dass die Anfrage vorübergehend nicht verfügbar ist; ein 503 nach einer unsicheren Übermittlung belegt nicht, dass kein Auftrag angelegt wurde. Wiederholen Sie die Anfrage daher mit demselben Idempotenzschlüssel. Fehler enthalten einen Code, eine Meldung und eine Anfrage-ID.

Kostenlose Sandbox

Testschlüssel akzeptieren nur diese Adressen: deliverable@example.com, undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com und error@example.com. Sie simulieren die Ergebnisse gültig, ungültig, Catch-all, unbekannt, ausstehend und nicht verfügbar. Bulk-Testjobs unterstützen Status, Ergebnisse, Abbruch und Wiederholung, ohne die Live-Verifizierung oder das Credit-Konto zu berühren.

Bulk-Sandbox-Jobs und ihre Wiederholungsdatensätze werden 30 Tage lang aufbewahrt. Verwenden Sie danach für einen neuen Test einen neuen Idempotenzschlüssel.

Der ursprüngliche /api/v1/verifications-Simulator für Testschlüssel verwendet seine frühere Antwortversion 2026-10-01 und camelCase-Felder. Verwenden Sie /api/v1/jobs für den versionierten Bulk-Simulator.

Signierte Webhooks

Die Rollen Inhaber und Manager konfigurieren HTTPS-Endpunkte für job.completed und job.canceled. Ein Test-Ping verwendet test.ping. Auftrags-Payloads enthalten eine stabile Ereignis-ID, Auftrags-ID, Status, eine Zusammenfassung ohne Adressen, die Anzahl abgebuchter und zurückgebuchter Credits sowie eine Ergebnis-URL. Sie enthalten nie E-Mail-Adressen oder Anbieterdaten.

Lesen Sie FairValid-Webhook-Id, FairValid-Webhook-Timestamp und FairValid-Webhook-Signature. Die Signatur ist fv1=, gefolgt von einem HMAC-SHA256-Hexwert in Kleinbuchstaben über die Rohbytes von fv1\n{event ID}\n{Unix timestamp}\n, unmittelbar gefolgt vom rohen JSON-Body. Verwenden Sie einen zeitkonstanten Vergleich. Lehnen Sie Zeitstempel ab, die mehr als fünf Minuten von Ihrer Uhrzeit abweichen, und deduplizieren Sie anhand der Event-ID in dauerhaftem Speicher.

Geben Sie innerhalb von 10 Sekunden einen beliebigen 2xx-Status zurück. Fehlgeschlagene oder unklare Zustellungen werden bis zu achtmal mit derselben Event-ID wiederholt; prüfen Sie den Verlauf der letzten 30 Tage oder stellen Sie manuell erneut zu. Weiterleitungen und private Ziele werden abgelehnt. Nach einer Rotation verwenden neue Versuche das neue Secret. Bewahren Sie das vorherige Secret 24 Stunden lang auf, um Signaturen bereits laufender Versuche zu verifizieren.

Ausführbare Beispiele

Das Repository enthält packages/contracts/examples/job.mjsund packages/contracts/examples/webhook-receiver.mjs. Führen Sie das Auftragsbeispiel mit Node 22 und einem Testschlüssel aus. Der Empfänger prüft die exakten Bytes des Raw Body sowie während der Rotation sowohl das aktuelle als auch das vorherige Secret. Schalten Sie HTTPS davor und ersetzen Sie die In-Memory-Menge der Event-IDs vor dem Produktiveinsatz durch einen dauerhaften, atomaren Speicher.

FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
  node packages/contracts/examples/job.mjs