REST-API-Referenz für Email Verifier

Die Email Verifier API wird unter /api/v1 bereitgestellt. Verwende den TrekMail-Host, über den sich dein Konto anmeldet. Die folgenden Beispiele verwenden https://YOUR-TREKMAIL-HOST als Platzhalter.

Authentifizierung und Scopes

Übermittle ein API-Token im Authorization-Header:

Authorization: Bearer YOUR_API_TOKEN

Aktiviere die Scopes beim Erstellen des Tokens:

Erteile einem Client beide Scopes, wenn er Arbeit einreichen und das Ergebnis anschließend lesen oder herunterladen muss.

Host und Anfrageformat

Alle Beispiele verwenden JSON-Anfrageinhalte und ein Bearer-Token. Der Datei-Uploader im Dashboard ist von der API getrennt: POST /verify/bulk akzeptiert ein JSON-Array emails, keine Multipart-Datei. Verwende exakt den Host, der zu Konto und Token gehört. Gehe nicht davon aus, dass Token oder Guthaben eines Markenhosts auf einem anderen Host funktionieren.

Sende Content-Type: application/json bei Anfragen an POST /verify und POST /verify/bulk. Bewahre Token und Idempotenzwert außerhalb von clientseitigem Code auf.

Idempotenz

POST /api/v1/verify/bulk und DELETE /api/v1/verify/bulk/{jobId} erfordern einen Idempotency-Key-Header. Erzeuge für jeden beabsichtigten Vorgang einen neuen Wert und verwende ihn nur erneut, wenn du denselben Vorgang wiederholst.

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

Einzelverifizierung und Auftragsabbruch benötigen diesen Header nicht. Eine Sammelanfrage ist außerdem innerhalb von 24 Stunden durch die Erkennung derselben normalisierten Liste und desselben Modus geschützt. Für Wiederholungen bleibt der Idempotenzschlüssel dennoch der richtige Mechanismus.

Unsicheres Netzwerkergebnis behandeln

Wenn deine Anwendung die Antwort auf eine Sammelanfrage verliert, erzeuge keinen neuen Idempotenzschlüssel und reiche die Liste nicht erneut ein. Wiederhole die identische Anfrage mit demselben Schlüssel. Speichere ihn zusammen mit der Kennung der Quellliste, bis TrekMail eine Auftrags-ID liefert. So bleibt die Wiederholung mit dem ursprünglich beabsichtigten Vorgang verbunden und verursacht keine vermeidbare zweite Belastung.

Endpunktübersicht

Stelle jedem Pfad in dieser Tabelle /api/v1 voran.

Guthaben lesen

GET /api/v1/verify/credits

Auf dem normalen TrekMail-Host enthält die Antwort das Tarifkontingent und gekauftes Guthaben:

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

Auf einem White-Label-Host steht dem Markenprodukt nur gekauftes Guthaben zur Verfügung. Die Antwort enthält daher purchased_balance und total_available.

Beispielanfrage:

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/credits \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Lies den Saldo unmittelbar vor einer großen Einreichung. Eine Saldoantwort ist eine Momentaufnahme. Eine Anwendung, die mehrere Aufträge einreicht, sollte daher den in jeder Sammelantwort berechneten Betrag erfassen, statt ihn später aus einer veralteten Zahl zu berechnen.

Saldo-Felder

White-Label-Saldoantworten haben absichtlich weniger Felder, da das Markenprodukt nur gekauftes Guthaben verwendet.

Eine Adresse prüfen

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

Die Antwort enthält email, status, trust_score, checks, provider, risk_factors und credits_remaining. Auf dem normalen Host enthält credits_remaining die Werte monthly und purchased. Die genaue Form von checks kann je nach Modus und den vom empfangenden Anbieter verfügbaren Informationen variieren.

Quick kostet 1 Guthaben. Deep kostet normalerweise 2 Guthaben, während anbieterspezifische Ausnahmen mit 1 Guthaben berechnet werden. Kann die Verifizierung nach der Belastung nicht ausgeführt werden, erstattet die Einzelanfrage diese Belastung und gibt eine Antwort zur vorübergehenden Nichtverfügbarkeit zurück.

Beispielanfrage:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

Verwende status, trust_score, provider und risk_factors auf oberster Ebene als normalen Anwendungsvertrag. checks enthält nützliche Nachweise, doch einzelne Schlüssel können abweichen, wenn eine externe Prüfung übersprungen wird, nicht verfügbar ist oder Deep zusätzliche Informationen erhält.

Einzelnes Ergebnis interpretieren

Lass eine Anwendung eine akzeptierte externe Antwort nicht als Besitz- oder Berechtigungsprüfung behandeln. Verwalte Abonnement-, Abmelde- und Kontaktpräferenzentscheidungen getrennt.

Sammelauftrag erstellen

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

Duplikate werden vor der Preisberechnung normalisiert. Ein erfolgreich erstellter Auftrag gibt 201 zurück:

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe und skip erklären die Deep-Preisberechnung. deep_savings ist die Differenz gegenüber der Berechnung jeder eingereichten Adresse zum vollen Deep-Tarif. Bei einer doppelten Liste werden vorhandene job_id und Status zurückgegeben, statt einen weiteren Auftrag zu starten.

Beispielanfrage:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -d '{"name":"September contacts","mode":"deep","emails":["first@example.com","second@example.net"]}'

Die API prüft eingereichte Werte vor der Auftragsannahme auf gültige E-Mail-Syntax. Werden alle Einträge zurückgewiesen, gibt sie 422 zurück und erstellt keinen Auftrag. Bei teilweiser Zurückweisung nennt die erfolgreiche Antwort rejected_count und bis zu fünf Werte in rejected_sample. Verlasse dich nicht auf diese kleine Stichprobe als vollständigen Bereinigungsbericht. Bewahre das Ergebnis der Quellvalidierung in deinem Importer auf.

Checkliste für Sammeleinreichungen

1. Lies und normalisiere die Quelle in deiner Anwendung.
2. Begrenze die Anfrage auf 50,000 eingereichte Einträge.
3. Erzeuge und speichere vor der Anfrage einen Idempotenzschlüssel.
4. Wähle einen aussagekräftigen Auftragsnamen, den Bediener später erkennen.
5. Speichere die von TrekMail zurückgegebenen Werte job_id, credits_charged und die Preisaufschlüsselung.
6. Frage die gespeicherte job_id ab und leite den Abschluss nicht aus der ursprünglichen HTTP-Anfrage ab.

Auftrag lesen

GET /api/v1/verify/bulk/{jobId}

Die Basisantwort enthält job_id, name, status, total, processed, progress, summary, created_at und completed_at.

Wenn Ergebnisse für einen abgeschlossenen, teilweisen oder fehlgeschlagenen Auftrag verfügbar sind, enthält die Antwort außerdem:

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

Optionale Abfrageparameter:

Ein abgebrochener Auftrag mit verarbeiteten Zeilen kann heruntergeladen werden. Verwende für seinen Export den Download-Endpunkt.

Auftragsstatus ohne Vermutungen lesen

Ein API-Client sollte mit zunehmender Wartezeit abfragen. Reiche keinen neuen Sammelauftrag ein, nur weil der vorhandene noch aussteht oder eine Netzwerkanfrage lokal abgelaufen ist.

Beispiel einer Statusantwort

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

summary kann mit fortschreitender Verarbeitung wachsen. Verwende processed und total für eine Fortschrittsanzeige, statt nur die Kategorien zu summieren, die deine Anwendung derzeit kennt.

Auftrag herunterladen

GET /api/v1/verify/bulk/{jobId}/download

Der Download ist für abgeschlossene, teilweise oder abgebrochene Aufträge mit verarbeiteten Zeilen verfügbar. Er streamt eine CSV mit den Spalten Email, Status, Trust Score, Provider und Risk Factors.

Beispiel:

curl -o september-results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe_risky" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Speichere die heruntergeladene Ausgabe innerhalb der 15-tägigen Aufbewahrungsfrist für Ergebnisse. Die CSV ist ein Export für deinen Ablauf. Sie ändert weder Einwilligungen noch Abonnements oder Kontakteinträge in einem anderen System.

Der Download-Endpunkt gibt einen Konflikt zurück, solange kein verarbeiteter Export verfügbar ist. Prüfe zuerst den Auftragsstatus. Eine erfolgreiche Anfrage streamt die CSV statt eines JSON-Wrappers. Behandle sie daher im HTTP-Client als Dateiantwort.

Aufträge auflisten

GET /api/v1/verify/bulk

Verwende page, per_page und optional status. per_page ist standardmäßig 20 und akzeptiert 1 bis 100. Mögliche Auftragsstatus sind pending, processing, completed, partial, cancelled und failed.

Die Antwort enthält ein Array jobs und ein Objekt pagination. Jeder Auftragseintrag enthält ID, Name, Status, Gesamtzahl, verarbeitete Anzahl, Fortschritt und Zeitstempel.

Beispiel:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Verwende den Listen-Endpunkt, wenn dein Worker neu startet oder du Auftrags-IDs abgleichen musst. Behandle einen Auftragsnamen nicht als eindeutige Kennung. Speichere die zurückgegebene numerische job_id.

Form der Auftragslisten-Antwort

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

Verwende den Abfrageparameter status, wenn eine Betriebsseite nur aktive oder nur abgeschlossene Arbeit benötigt. Paginierung ist für Konten mit vielen verifizierten Listen wichtig. Gehe nicht davon aus, dass eine Antwort den gesamten Verlauf enthält.

Auftrag abbrechen

POST /api/v1/verify/bulk/{jobId}/cancel

Brich nur ausstehende oder laufende Arbeit ab. Eine erfolgreiche Antwort lautet:

{"status":"cancelled","credits_refunded":40}

Die Erstattung gilt für unverarbeitete Arbeit. Erreicht der Auftrag einen Endstatus, bevor der Abbruch ihn erreicht, gibt die API einen Konflikt zurück, statt das Ergebnis zu ändern.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ein Abbruch löscht den Auftrag nicht. Lade verarbeitete Zeilen bei Bedarf herunter oder lösche den abgeschlossenen Datensatz anschließend.

Auftrag löschen

DELETE /api/v1/verify/bulk/{jobId}

Brich einen laufenden Auftrag zuerst ab. Das Löschen entfernt Auftrag und Ergebnisse dauerhaft, nachdem TrekMail die bereitgestellte Quellliste sicher entfernt hat. Eine erfolgreiche Antwort lautet:

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

Dieser Vorgang ist für den Verifier-Datensatz dauerhaft. Bereits von deiner Anwendung heruntergeladene CSV-Dateien werden nicht zurückgezogen. Wende deshalb deinen eigenen Aufbewahrungsprozess auf diese Kopien an.

Löschreihenfolge

1. Lies den Auftragsstatus.
2. Brich ihn ab, wenn er aussteht oder verarbeitet wird.
3. Speichere jeden verarbeiteten Export, den du aufbewahren musst.
4. Lösche den nicht laufenden Verifier-Auftrag mit einem Idempotenzschlüssel.
5. Entferne Kopien deines Systems nach dessen Datenschutz- und Aufbewahrungsregeln.

Fehler und Wiederholungen

Die Einzelverifizierung hat ein Routenlimit von 60 Anfragen pro Minute, die Sammeleinreichung eines von 10 Anfragen pro Minute. Implementiere Wiederholungen mit zunehmender Wartezeit, behalte bei einer Sammelwiederholung denselben Idempotenzschlüssel und wiederhole eine Anfrage nach einem unbekannten Netzwerkergebnis nicht blind.

Sicheres Wiederholungsmuster

1. Erzeuge und speichere vor einer Sammeleinreichung einen Idempotenzschlüssel.
2. Sende die Anfrage mit diesem Schlüssel.
3. Geht die Antwort verloren, wiederhole die identische Anfrage mit demselben Schlüssel.
4. Speichere die zurückgegebene job_id und erstelle für diese Quellliste keine neuen Einreichungen.
5. Frage den Auftrag bis zum Endstatus ab und lade oder verarbeite dann das Ergebnis.

Bei einer Einzelverifizierung bedeutet ein vorübergehender 503, dass der Dienst die Prüfung nicht abschließen konnte. Versuche es später mit normaler zunehmender Wartezeit erneut. Wandle diese Antwort in deiner Datenbank nicht in ein Invalid-Ergebnis um.

Kontaktdaten schützen

E-Mail-Listen sind in vielen Zusammenhängen personenbezogene Daten. Sende nur die für die Verifizierung benötigten Daten, beschränke den Token-Zugriff auf das System, das den Auftrag ausführt, und vermeide vollständige Adressarrays in Anwendungsprotokollen. Protokolliere bei Bedarf Auftrags-ID, Anzahl, Zeitangaben und Ergebnis auf hoher Ebene statt der vollständigen Liste.

TrekMail bewahrt Ergebnisse 15 Tage auf. Plane vor der Integration großer Listen einen eigenen sicheren Speicher- oder Löschpfad für Exporte.

Verifizierungssignale beweisen weder Besitz noch Einwilligung oder künftige Zustellung einer Person. Verwalte Berechtigungen und Unterdrückung weiter in deiner Anwendung, selbst wenn eine Adresse Safe erreicht.