Schnellstart für die TrekMail Email Verifier API

Verwende die API, wenn die Verifizierung Teil deines Produkts oder Importablaufs sein soll. Erstelle ein Token mit verify:read und verify:write, halte es geheim und rufe denselben Host auf, über den du dich anmeldest. Ersetze in den Beispielen https://YOUR-TREKMAIL-HOST und YOUR_API_TOKEN.

1. Token erstellen

1. Öffne Dashboard → AI Agents & API.
2. Erstelle ein Token.
3. Aktiviere verify:read und verify:write.
4. Bewahre das Token sicher auf. Es wird nur einmal angezeigt.

Sende es mit jeder Anfrage:

Authorization: Bearer YOUR_API_TOKEN

Bewahre das Token in einem Secret Store oder einer Umgebungsvariable auf. Füge es nicht in Browsercode, ein öffentliches Repository, eine Supportanfrage oder eine exportierte Kontaktdatei ein. Wenn es offengelegt worden sein könnte, widerrufe es und erstelle im Dashboard einen Ersatz.

2. Eine Adresse prüfen

Verwende POST /api/v1/verify, um sofort das Ergebnis für eine einzelne Adresse zu erhalten. Quick ist die Vorgabe, wenn mode fehlt.

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"}'

Die Antwort enthält stabile Felder auf oberster Ebene, darunter Adresse, Status, Vertrauenswert, Anbieter, Risikofaktoren und verbleibendes Guthaben. Das Objekt checks erfasst die einzelnen Nachweise und kann variieren, wenn eine Prüfung nicht verfügbar ist oder der Deep-Modus zusätzliche Informationen liefert.

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

Lies zuerst status und trust_score. Betrachte einzelne Prüfschlüssel als ergänzende Details, nicht als Garantie für Postfachbesitz oder Zustellung.

Der Einzel-Endpunkt hat ein Routenlimit von 60 Anfragen pro Minute. Wenn du eine bei der Registrierung eingegebene Adresse prüfst, rufe ihn nach einer grundlegenden clientseitigen Validierung auf. Zeige bei vorübergehender Nichtverfügbarkeit einen verständlichen Fehler, statt die Person unbegrenzt zu blockieren.

3. Sammelauftrag übermitteln

Sammelanfragen akzeptieren ein JSON-Array emails, keinen Datei-Upload. Füge einen Idempotenzschlüssel hinzu, damit ein erneuter Netzwerkversuch keinen zweiten Auftrag erstellt.

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

Die Liste kann bis zu 50,000 Einträge enthalten. TrekMail normalisiert Duplikate und weist syntaktisch ungültige Einträge aus dem Auftrag zurück. Die Antwort nennt Auftrags-ID, akzeptierte Anzahl, eine kleine Stichprobe der Zurückweisungen, berechnetes Guthaben und die Deep-Preisaufschlüsselung.

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

probe ist die Anzahl zum vollen Deep-Tarif. skip ist die Anzahl zum regulären Tarif, weil der Anbieter keine brauchbaren Nachweise auf Postfachebene anbietet. Die Antwort nennt die verbindlichen Kosten dieser Einreichung.

Entferne vor dem Einreichen einer vollständigen Liste Werte, die keine Adressen sind, in deinem eigenen Importer. Die API dedupliziert Adressen und meldet eine Anzahl zurückgewiesener Einträge, doch die Quellvalidierung schafft eine klarere Prüfspur. Läuft die Anfrage aus Sicht deiner Anwendung in ein Timeout, wiederhole dieselbe Sammelanfrage mit demselben Idempotenzschlüssel und prüfe die zurückgegebene Auftrags-ID, bevor du eine weitere Einreichung erstellst.

4. Status abfragen und herunterladen

Frage den Auftrag mit GET /api/v1/verify/bulk/{jobId} ab, bis er einen Endstatus erreicht:

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

Die Antwort enthält status, total, processed, progress, summary, Erstellungszeit und Abschlusszeit. Abgeschlossene und teilweise verarbeitete Aufträge enthalten ein paginiertes results-Array.

Frage in sinnvollen Abständen mit zunehmender Wartezeit ab. Ein Auftrag kann vor Arbeitsbeginn ausstehend bleiben, und Deep kann länger dauern, wenn ein empfangender Anbieter zusätzliche Nachweise liefert. Leite keine feste Abschlusszeit allein aus der Listengröße ab.

Du kannst eine kleinere Ergebnisseite anfordern oder nach Verfügbarkeit der Ergebnisse eine bekannte Adresse suchen:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Lade einen verarbeiteten Auftrag als CSV herunter:

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

Die API-Exportfilter sind all, safe und safe_risky (Safe + Valid + Risky).

Verwende den Abbruch-Endpunkt, um einen ausstehenden oder laufenden Auftrag zu stoppen. Er erstattet unverarbeitete Arbeit und behält verarbeitete Zeilen:

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

Lösche einen Auftrag nur, wenn du sowohl seinen Verifier-Datensatz als auch seine Ergebnisse entfernen willst. Läuft er noch, brich ihn zuerst ab und verwende danach den Lösch-Endpunkt mit einem Idempotenzschlüssel. Die vollständige Referenz zeigt beide Aufrufe.

5. Übliche Antworten behandeln

• 402: Das Konto benötigt mehr Guthaben.
• 422: Prüfe Anfrageinhalt, ausgewählten Modus oder den für eine Sammelanfrage erforderlichen Idempotenzschlüssel.
• 429: Reduziere die Frequenz und versuche es mit zunehmender Wartezeit erneut.
• 503: Die Verifizierung ist vorübergehend nicht verfügbar. Versuche es später erneut. Eine fehlgeschlagene Einzelprüfung wird erstattet.

Checkliste für eine Produktionsintegration

1. Bewahre das Token serverseitig auf und erteile nur die beiden erforderlichen Verifier-Scopes.
2. Validiere und normalisiere Kontakte vor dem Aufruf der Sammel-API.
3. Speichere Auftrags-ID, Kennung der eingereichten Liste, Idempotenzschlüssel und den zurückgegebenen Wert credits_charged.
4. Frage mit zunehmender Wartezeit ab, statt eine enge Schleife zu verwenden.
5. Speichere oder verarbeite die CSV vor Ablauf der 15-tägigen Aufbewahrungsfrist.
6. Pflege Entscheidungen zu Einwilligung, Abmeldung und Unterdrückung in deiner eigenen Anwendung. Ein Verifier-Ergebnis ersetzt sie nicht.

Alle Endpunkte, Scopes und Antwortfelder findest du in der REST-API-Referenz für Email Verifier.