API-Workflow zur E-Mail-Validierung: Von der Sandbox in die Produktion mit FairValid

API-Workflow zur E-Mail-Validierung: Vom Sandbox-Test zu Produktionsergebnissen

Frage: Sie sind Entwickler und integrieren die E-Mail-Verifizierung in Ihr eigenes System. Welche Schritte führen Sie vom ersten Testaufruf zu verlässlichen Produktionsergebnissen?

Kurze Antwort: Beginnen Sie mit einem Test-Schlüssel und der kostenlosen Sandbox. Wechseln Sie dann zu einem Live-Schlüssel, der nur die Berechtigungen hat, die Sie benötigen. Senden Sie jede Übermittlung mit einem Idempotenzschlüssel. Lesen Sie den Job-Status aus und rufen Sie die Ergebnisse seitenweise ab. Behandeln Sie jedes Ergebnis und jeden Fehlercode einzeln. Die folgenden Schritte orientieren sich an der API-Referenz für Kunden von FairValid.

Schritt 1: Zuerst gegen die Sandbox entwickeln

Erstellen Sie auf der Seite für API-Schlüssel einen Test-Schlüssel und bewahren Sie ihn auf Ihrem Server auf. Die Referenz verwendet zwei Umgebungsvariablen, FAIRVALID_API_KEY und FAIRVALID_BASE_URL. Test-Schlüssel lösen keinen Anbieteraufruf aus und verbrauchen keine Credits.

Test-Schlüssel akzeptieren nur eine kleine Auswahl reservierter Adressen auf der Domain example.com. Diese Adressen simulieren die Ergebnisse gültig, ungültig, Catch-all, unbekannt, ausstehend und nicht verfügbar. Die genauen Adressen finden Sie im Abschnitt „Kostenlose Sandbox“ der API-Referenz. Test-Jobs liefern feste, reproduzierbare Status: abgeschlossen, ausstehend, fehlgeschlagen oder abgebrochen. Bulk-Test-Jobs unterstützen Status, Ergebnisse und Abbruch.

Die Sandbox zeigt Ihnen genau diese Ergebnisse. Sie deckt nicht jeden Pfad ab, den Ihre Integration nehmen kann. Planen Sie daher eine gesonderte Behandlung der in Schritt 7 beschriebenen Fehlercodes ein.

Bulk-Test-Jobs sind auf 20 neue Jobs pro Workspace und Stunde bzw. 100 pro 30 Tage begrenzt. Wird eines dieser Limits überschritten, wird HTTP 429 zurückgegeben. Ein identischer Wiederholungsversuch liefert weiterhin den ursprünglichen Job.

Schritt 2: Zu einem Live-Schlüssel mit den benötigten Berechtigungen wechseln

Erstellen Sie für die Produktion einen Live-Schlüssel mit der Berechtigung submit. Verwenden Sie POST /api/v1/jobs für Batches oder POST /api/v1/verifications für eine einzelne Adresse. Fügen Sie die Berechtigung read hinzu, wenn der Schlüssel auch Job-Status und Ergebnisse lesen muss. Live-Schlüssel können zusätzlich die Berechtigung balance erhalten. Unabhängig davon liest GET /api/v1/balance die verfügbaren und reservierten Credits des Workspace aus. Das vollständige Secret wird nur einmal angezeigt. Speichern Sie es daher beim Erstellen des Schlüssels sicher.

Live-Jobs nutzen die Verifizierungswarteschlange und das Credit-Guthaben Ihres Workspace. Schlüsselberechtigungen, Schlüssel-Limits, Workspace-Zugriff und Verarbeitungslimits gelten weiterhin.

Schritt 3: Einen Job mit Idempotenzschlüssel übermitteln

Ein Job akzeptiert 1 bis 5.000 Adressen im JSON-Format, bis zu 2 MiB. Senden Sie bei jeder Job-Übermittlung und jeder Live-Übermittlung einer einzelnen Adresse einen Idempotency-Key-Header. Der Schlüssel muss 8 bis 128 Zeichen lang sein und darf Buchstaben, Ziffern, Punkte, Doppelpunkte, Unterstriche oder Bindestriche enthalten.

• Ein neuer Job liefert HTTP 202 mit einer UUID job_id.
• Ein passender Wiederholungsversuch liefert HTTP 200 mit demselben Job.
• Wird ein Idempotenzschlüssel mit geändertem Body wiederverwendet, wird HTTP 409 idempotency_conflict zurückgegeben.

Wenn Sie nicht feststellen können, ob eine Anfrage angekommen ist, wiederholen Sie sie mit demselben API-Schlüssel, demselben Idempotenzschlüssel und demselben normalisierten Body. Die Wiedergabe ist an den API-Schlüssel gebunden. Wenn Sie diese Zugangsdaten ersetzen und erneut übermitteln, kann daher ein zweiter Durchlauf entstehen. Verwenden Sie einen neuen Idempotenzschlüssel nur, wenn Sie tatsächlich einen neuen Durchlauf wünschen, der kostenpflichtig sein kann.

Schritt 4: Den Job auslesen und Ergebnisse seitenweise abrufen

Lesen Sie den Job mit GET /api/v1/jobs/{id} aus. Sein Status kann queued, running, paused, canceling, canceled oder completed sein. Lesen Sie die Ergebnisse mit GET /api/v1/jobs/{id}/results aus. Jede Seite liefert bis zu 50 Ergebnisse sowie einen signierten next_cursor. Übergeben Sie diesen Wert als Query-Parameter cursor. Ihr ursprünglicher Filter und Ihre Suche bleiben dabei erhalten.

Die Filter lauten all, valid, invalid, catch_all, unknown, still_checking und not_checked. Um einen Job zu stoppen, fordert POST /api/v1/jobs/{id}/cancel den Abbruch an; bereits laufende Arbeit kann jedoch noch abgeschlossen werden.

Die Referenz beschreibt außerdem ein signiertes Abschluss-Event und verlinkt auf die Webhook-Verwaltung.

Schritt 5: Jedes Ergebnis als eigenen Status behandeln

Der Leitfaden zu den Ergebnissen erklärt, was jedes Ergebnis bedeutet:

• Gültig: eine verwertbare positive Prüfung. Sie garantiert niemals die Zustellung in den Posteingang.
• Ungültig: Die Adresse hat die Prüfung nicht bestanden.
• Catch-all: Die Domain akzeptiert möglicherweise viele Adressen, sodass eine Aussage auf Postfachebene weniger sicher sein kann. Lesen Sie die Details, bevor Sie das Ergebnis verwenden.
• Unbekannt: Die Prüfung konnte keine verlässliche Antwort liefern.
• Prüfung läuft noch: Es liegt noch keine endgültige Antwort vor.

Der Leitfaden beschreibt technische Fehler und nicht verarbeitete Einträge getrennt von „Unbekannt“, und die API bietet unknown, still_checking und not_checked als separate Filter an. Führen Sie diese Status in Ihren eigenen Daten in getrennten Feldern oder Status, statt sie unter „Unbekannt“ zusammenzufassen.

Schritt 6: Credit-Reservierungen verstehen, bevor Sie abgleichen

Laut der API-Referenz werden Workspace-Credits reserviert, sobald Prüfungen zur Verarbeitung zugelassen werden. Für die Ergebnisse gelten anschließend dieselben Abrechnungs- und Rückgaberegeln wie im Dashboard. Laut der Preisseite von FairValid hält eine Credit-Reservierung Kapazität für eine laufende Prüfung frei, und das endgültige Ergebnis bestimmt die Abrechnung:

• Gültig oder ungültig: 1 Credit pro abgeschlossenem Ergebnis.
• Unbekannt oder Catch-all: Letztlich werden keine Verifizierungs-Credits abgezogen. Reservierte Credits werden freigegeben oder zurückgebucht.
• Prüfung läuft noch: noch keine endgültige Abbuchung. Eine Reservierung ist keine abgeschlossene Abbuchung.
• Technische Fehler und nicht verarbeitete Arbeit: Letztlich werden keine Verifizierungs-Credits abgezogen. Reservierungen werden freigegeben oder zurückgebucht.

Wenn Sie Ihr Guthaben während eines laufenden Jobs prüfen, denken Sie daran, dass reservierte Credits noch keine endgültigen Abbuchungen sind. Gleichen Sie erst ab, wenn die Ergebnisse endgültig sind. Jedes Konto enthält 300 kostenlose Credits pro Monat. Sie werden zuerst verbraucht und verfallen am Monatsende. Gekaufte Credits bleiben verfügbar, solange das Konto besteht.

Schritt 7: Fehler nach Ursache behandeln, nicht mit einer einzigen Wiederholungsregel

• 401: Der Schlüssel fehlt, wurde widerrufen oder hat nicht die nötige Berechtigung. Korrigieren Sie die Zugangsdaten oder deren Berechtigungen.
• 402 key_cap_reached: Die neue Anfrage würde das Gesamtlimit des Schlüssels überschreiten; es wurden weder ein Job noch eine Reservierung angelegt. Das Limit zählt bereits abgebuchte Credits plus Credits, die für akzeptierte eindeutige Identitäten reserviert sind. Da es sich um ein Gesamtlimit über die gesamte Lebensdauer handelt, wird es nicht mit der Zeit wieder aufgefüllt, und Abwarten hebt es nicht auf. Lassen Sie die Limit-Einstellung dieses Schlüssels von einer Person mit entsprechendem Zugriff prüfen. Ein Limit kann dem Workspace keine Credits hinzufügen.
• 422: ungültige Adressen oder überschrittene Listenlimits. Korrigieren Sie die Eingabe.
• 503 live_verification_unavailable: Während einer betrieblichen Pause kann eine neue Live-Übermittlung diesen Fehler zurückgeben, ohne Credits zu reservieren. Versuchen Sie es später mit demselben Idempotenzschlüssel erneut. Ein 503 nach einer unsicheren Übermittlung beweist nicht, dass kein Job angelegt wurde. Verwenden Sie daher den ursprünglichen Schlüssel erneut.

Jeder Fehler enthält einen Code, eine Meldung und eine Anfrage-ID. Protokollieren Sie alle drei, damit Sie sie zur Hand haben, falls Sie den Support kontaktieren.

Eine sinnvolle Reihenfolge

1. Entwickeln Sie die Integration gegen die Sandbox und prüfen Sie, ob jedes simulierte Ergebnis dort landet, wo Sie es erwarten.
2. Ergänzen Sie eine explizite Behandlung der oben genannten Fehlercodes.
3. Erstellen Sie einen Live-Schlüssel mit den engsten Berechtigungen, die Sie benötigen, und einem Limit, das zu Ihrem Budget passt.
4. Beginnen Sie mit einem kleinen Live-Job. Vergleichen Sie dessen Ergebnisse und Credit-Status mit dem Dashboard und skalieren Sie dann hoch.

Wenn Sie diesen Workflow ausprobieren möchten, können Sie in der kostenlosen Sandbox die simulierten Ergebnisse testen, ohne Credits zu verbrauchen. Die genauen Anfragedetails finden Sie in der API-Referenz.