Bulk-E-Mail-Verifizierung per API: Ein praxisnaher Workflow für Batch-Jobs

Bulk-E-Mail-Verifizierung per API: Ein praxisnaher Workflow für Batch-Jobs

Die Frage: Sie haben eine große Adressliste in Ihrem eigenen System. Wie senden Sie sie stapelweise über die FairValid API, behandeln Fehler sicher und lesen die Ergebnisse zurück, ohne den Überblick über Ihre Credits zu verlieren?

Kurze Antwort: Beginnen Sie in der Sandbox mit einem Test-Schlüssel. Teilen Sie die Liste dann in Jobs mit bis zu 5.000 Adressen auf und geben Sie jedem Job einen eigenen Idempotenzschlüssel. Reichen Sie jeden Job mit einem Live-Schlüssel ein, prüfen Sie seinen Status und blättern Sie die Ergebnisse nach Resultat durch. Behandeln Sie ausstehende Prüfungen, technische Fehler und Ergebnisse mit „Unbekannt“ als drei getrennte Situationen.

Belege geprüft am 13. November 2026 anhand der API-Referenz, des Ergebnisleitfadens und der Credit-Regeln von FairValid.

Schritt 1: Zuerst gegen die Sandbox entwickeln

Laut der API-Referenz erstellen Sie unter API-Schlüssel einen Test-Schlüssel, bewahren ihn auf Ihrem Server auf und hinterlegen ihn zusammen mit der Basis-URL in Ihrer Umgebung. Test-Schlüssel funktionieren mit reservierten Adressen der Domain example.com. Sie lösen keine Anbieteraufrufe aus und verbrauchen keine Credits. Test-Schlüssel greifen auf ihre eigenen simulierten Jobs zu.

Test-Jobs liefern deterministische Zustände: abgeschlossen, ausstehend, fehlgeschlagen oder abgebrochen. Die genauen Sandbox-Adressen finden Sie in der API-Referenz; prüfen Sie damit, ob Ihr Code diese Zustände verarbeitet. Diese Fälle zeigen nur die Ergebnisse, für die sie konzipiert wurden. Sie decken nicht jeden Zweig Ihrer Integration ab, prüfen Sie Ihre eigenen Fehlerpfade also separat.

Schritt 2: Zu einem Live-Schlüssel mit den richtigen Berechtigungen wechseln

Für den Produktivbetrieb benötigen Sie laut API-Referenz einen Live-Schlüssel mit der Berechtigung submit, um Jobs zu erstellen. Fügen Sie die Berechtigung read hinzu, um Job-Status und Ergebnisse zu lesen. Live-Schlüssel können außerdem die Berechtigung balance erhalten. Vollständige Schlüssel-Secrets werden nur einmal angezeigt, speichern Sie sie daher beim Erstellen sicher auf Ihrem Server. Ein widerrufener Schlüssel stoppt neue Anfragen.

Live-Jobs nutzen die Verifizierungswarteschlange und das Credit-Guthaben Ihres Workspace. Schlüsselberechtigungen, Schlüssellimits, Workspace-Zugriff und Verarbeitungslimits gelten weiterhin. Ein Live-Schlüssel gewährt keinen unbegrenzten Zugriff.

Schritt 3: Liste aufteilen und Jobs einreichen

Jeder Job akzeptiert 1 bis 5.000 Adressen im JSON-Format, bis zu 2 MiB. So können Sie praktisch vorgehen:

1. Teilen Sie Ihre Liste in Abschnitte. Zur Veranschaulichung: Aus 12.000 Adressen würden drei Jobs mit 5.000, 5.000 und 2.000 Adressen.
2. Geben Sie jedem Abschnitt einen eigenen, stabilen Idempotency-Key und halten Sie fest, welche Ihrer Zeilen in welchen Abschnitt gegangen sind. Wenn Sie diese Zuordnung auf Ihrer Seite pflegen, lassen sich die Ergebnisse leichter wieder Ihren Datensätzen zuordnen.
3. Reichen Sie beim Jobs-Endpunkt ein. Ein neuer Job liefert HTTP 202 mit einer UUID als job_id. Ein passender Wiederholungsversuch liefert HTTP 200 mit demselben Job. Sie können also nach einem Timeout dieselbe Anfrage mit demselben Schlüssel erneut senden und erhalten den bestehenden Job zurück.

Schritt 4: Die zwei ähnlich aussehenden Fehler behandeln

Beide Antworten können eine Einreichung blockieren, bedeuten aber Unterschiedliches:

• HTTP 503 live_verification_unavailable kann während einer betrieblichen Pause zurückkommen. Laut API-Referenz werden dabei keine Credits reserviert. Versuchen Sie es später mit demselben Idempotency-Key erneut.
• HTTP 402 key_cap_reached bedeutet, dass eine neue Anfrage das lebenslange Ausgabenlimit des Schlüssels überschreiten würde. Dieses Limit umfasst bereits abgerechnete Credits plus Credits, die für akzeptierte eindeutige Identitäten reserviert sind. Es wird weder ein Job noch eine Reservierung angelegt. Ein lebenslanges Limit füllt sich mit der Zeit nicht wieder auf, Warten hilft also nicht. Prüfen Sie das Limit des Schlüssels in den API-Schlüsseleinstellungen oder verwenden Sie einen Schlüssel mit ausreichend verbleibendem Limit für die Arbeit. Ein Schlüssellimit kann dem Workspace auch keine Credits hinzufügen. Es begrenzt nur, was dieser Schlüssel ausgeben kann.

Protokollieren Sie diese beiden Antworten getrennt von Berechtigungsfehlern und Verarbeitungslimits, damit die richtige Person die richtige Benachrichtigung erhält.

Schritt 5: Job-Status verfolgen und Ergebnisse seitenweise abrufen

Der Job-Endpunkt liefert den aktuellen Zustand und eine Zusammenfassung eines Jobs. Der Job-Status kann in der Warteschlange, laufend, pausiert, wird abgebrochen, abgebrochen oder abgeschlossen sein. Wenn Sie einen Abbruch anfordern, kann bereits laufende Arbeit trotzdem noch abgeschlossen werden.

Der Ergebnis-Endpunkt liefert bis zu 50 Ergebnisse auf einmal, zusammen mit einem signierten next_cursor. Übergeben Sie diesen Wert als Abfrageparameter cursor. Er übernimmt Ihren ursprünglichen Filter und Ihre Suche. Die Filter lauten all, valid, invalid, catch_all, unknown, still_checking und not_checked. Damit können Sie gezielt nur die Zeilen abrufen, die eine Entscheidung erfordern, etwa alle als unknown markierten.

Schritt 6: Ergebnisse in Entscheidungen umsetzen

Der Ergebnisleitfaden beschreibt Ergebnisse als Belege, nicht als Zustellgarantie:

• Gültig steht für eine verwertbare positive Prüfung. Es garantiert nie die Zustellung in den Posteingang.
• Ungültig bedeutet, dass die Adresse die Prüfung nicht bestanden hat.
• Catch-all bedeutet, dass die Domain möglicherweise viele Adressen annimmt, sodass eine Aussage über das konkrete Postfach weniger sicher sein kann. Lesen Sie die Details, bevor Sie die Adresse verwenden.
• Unbekannt bedeutet, dass die Prüfung keine verlässliche Antwort liefern konnte.
• Wird noch geprüft bedeutet, dass noch keine endgültige Antwort vorliegt. Fragen Sie weiter ab und behandeln Sie es nicht als „Unbekannt“.

Technische Fehler und unverarbeitete Einträge bilden eine eigene Kategorie. Laut den Credit-Regeln von FairValid werden sie nicht in „Unbekannt“ umbenannt.

Schritt 7: Credit-Reservierungen verstehen

Laut API-Referenz werden Workspace-Credits reserviert, sobald Prüfungen zur Verarbeitung zugelassen werden. Für Ergebnisse gelten dieselben Abrechnungs- und Rückgaberegeln wie im Dashboard. Nach den Credit-Regeln kostet ein abgeschlossenes Ergebnis „Gültig“ oder „Ungültig“ einen Credit. Für „Unbekannt“ und ungeklärte „Catch-all“-Ergebnisse werden letztlich keine Credits abgezogen, da reservierte Credits freigegeben oder zurückgebucht werden. „Ausstehend“ ist kein endgültiges Ergebnis. Auch für technische Fehler und unverarbeitete Arbeit werden letztlich keine Credits abgezogen. Zurückgebuchte Credits behalten ihr ursprüngliches Kontingent und ihre ursprünglichen Ablaufregeln.

Der Guthaben-Endpunkt meldet verfügbare und reservierte Credits für den Live-Workspace. Ist das Feld free_allowance_held auf true gesetzt, ist das kostenlose Kontingent zurückgehalten und wird weder in available_credits noch in free_available gezählt. Bezahlte Credits bleiben verfügbar. Das ursprüngliche Konto erhält jeden Monat an seinem Registrierungsdatum 300 kostenlose Credits; ungenutzte kostenlose Credits verfallen und werden nicht übertragen. Zusätzliche Workspaces erhalten kein weiteres kostenloses Kontingent. Kostenlose Credits werden zuerst verbraucht, und bezahlte Credits verfallen nicht, solange das Konto besteht.

Eine einfache Checkliste

• Mit einem Test-Schlüssel und den dokumentierten Sandbox-Fällen testen.
• Einen Live-Schlüssel mit den Berechtigungen submit und read sowie einem zur geplanten Arbeit passenden Limit verwenden.
• Jeden Abschnitt auf höchstens 5.000 Adressen begrenzen, mit jeweils einem stabilen Idempotenzschlüssel pro Abschnitt.
• Bei 503 später mit demselben Schlüssel erneut versuchen. Bei 402 nicht abwarten, sondern das Limit anpassen.
• Ergebnisse mit dem signierten Cursor seitenweise abrufen, gefiltert nach Resultat.
• Ausstehend, technische Fehler und „Unbekannt“ in Ihren Daten getrennt halten.

Wenn Sie diesen Workflow ausprobieren möchten, können Sie vor Ihrer ersten Live-Einreichung einen Test-Schlüssel erstellen und einen Sandbox-Job ausführen, ohne Credits zu verbrauchen. Die vollständigen Endpunkt-Details finden Sie in der API-Referenz.