API-Referenz zur E-Mail-Prüfung

Authentifizierung

POST /v1/email/validate akzeptiert einen veröffentlichbaren, Origin-gebundenen Schlüssel im Header X-Api-Key – derselbe Schlüsseltyp und dasselbe Modell erlaubter Origins wie bei GET /v1/geo. Alle anderen Endpoints auf dieser Seite (Batch, Listenjobs, Registrierungsprüfung) akzeptieren viele Adressen oder eine beliebige IP, erfordern daher Ihren geheimen Schlüssel über Authorization: Bearer und dürfen nur aus Ihrem Backend aufgerufen werden; ein veröffentlichbarer Schlüssel erhält dort eine 403.

Beispiel

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

Urteile und Grundcodes

Jede Bedingung setzt ein Mindesturteil; die schwerwiegendste gewinnt, und reasons listet alle auf, die schwerwiegendste zuerst. Ob eine Adresse eines Freemail-Anbieters akzeptabel ist, entscheiden Sie – das Urteil ändert sich dadurch nie.

Batch-Prüfung

POST/v1/email/batch

Prüft 1–100 Adressen in einer Anfrage mit denselben Prüfungen und derselben Ergebnisform wie POST /v1/email/validate, ein Ergebnis pro Adresse in Eingabereihenfolge. Senden Sie { "emails": [...] }. Adressen derselben Domain teilen sich eine DNS-Abfrage. Zählt eine Anfrage pro Adresse gegen Ihr monatliches Tarifkontingent; ein Batch, der das Kontingent überschreiten würde, wird vollständig mit 429 monthly_limit_exceeded abgelehnt. Für die Ratenbegrenzung pro Minute zählt der gesamte Aufruf als eine Anfrage. Nur mit geheimem Schlüssel.

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

E-Mail-Listenjobs

POST/v1/email/jobs

Prüft bis zu 100.000 Adressen im Hintergrund. Senden Sie JSON { "emails": [...], "filename": "..." } oder einen text/csv-Body von höchstens 10 MB: Verwendet wird die Spalte mit der Überschrift email (auch e-mail, email address, email_address oder mail, ohne Beachtung der Groß-/Kleinschreibung) oder die erste Spalte, wenn keine Überschrift eine solche benennt; Komma, Semikolon und Tabulator als Trennzeichen werden erkannt. Der Job wird bei der Erstellung berechnet – eine Anfrage pro eindeutiger Adresse (exakte Übereinstimmung), Duplikate werden also geprüft, aber nur einmal berechnet – und eine Liste, die Ihr Monatskontingent überschreiten würde, wird vollständig abgelehnt. Kann ein Teil eines Jobs auch nach Wiederholungen nicht verarbeitet werden, wird der Job als failed markiert und die Credits für den nicht verarbeiteten Teil werden erstattet. Antwortet mit 202 und dem Job-Objekt. Nur mit geheimem Schlüssel; dieselben Jobs lassen sich auch auf der Dashboard-Seite Email lists hoch- und herunterladen.

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

Job-Status

GET/v1/email/jobs/{id}

Gibt dasselbe Job-Objekt zurück. Fragen Sie es ab, bis status completed ist; Abfragen werden nicht berechnet.

Job-Ergebnisse

GET/v1/email/jobs/{id}/results

Lädt eine CSV-Datei mit einer Zeile pro übermittelter Zeile herunter, in Übermittlungsreihenfolge – einschließlich Duplikaten. Spalten: email, normalized_email, verdict, reasons, syntax_valid, is_disposable, disposable_source, is_free_provider, is_role_account, did_you_mean, mx_status, mx_host. reasons ist durch Semikolons getrennt, leere Zellen bedeuten null, und mx_status ist bei syntaktisch ungültigen Adressen leer (es wurde nichts abgefragt). Einer ungültigen Adresse, die mit =, +, - oder @ beginnt, wird ein Apostroph vorangestellt, damit Tabellenkalkulationen sie nicht als Formel ausführen. 409, bis der Job abgeschlossen ist, 410, sobald er abgelaufen ist. Der Download wird nicht berechnet.

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

Registrierungsprüfung

POST/v1/signup/check

Bewertet eine Registrierung anhand von E-Mail-Adresse und IP in einem Aufruf, aus Ihrem Backend beim Absenden des Registrierungsformulars (ein im Browser berechnetes Urteil kann gefälscht werden). Senden Sie { "email": "...", "ip": "...", "userAgent": "..." } – userAgent ist optional. Die Antwort enthält das vollständige Ergebnis der E-Mail-Prüfung (email), Land und ASN der IP sowie – in Tarifen mit Sicherheitsdaten – ihre VPN-/Tor-/Rechenzentrums-/Bedrohungsindikatoren (ip), das Alter der E-Mail-Domain in Tagen laut öffentlichen Registrierungsdaten (RDAP) (emailDomainAgeDays, null wenn unbekannt und bei bekannten Endkunden-Anbietern), einen Score von 0–100 (die Summe der unten aufgeführten Gewichte der Gründe, begrenzt auf 100) und ein Urteil: reject ab 60, review ab 25, sonst accept. In einem Tarif ohne Sicherheitsdaten ist ip.security null, der Score nutzt nur die E-Mail-Signale und reasons enthält ip_security_unavailable. Zählt als eine Anfrage. Nur mit geheimem Schlüssel.

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

Limits

Jede geprüfte Adresse zählt als eine Anfrage gegen das gemeinsame Monatskontingent Ihres Tarifs – eine Einzelprüfung, jede Adresse in einem Batch, jede eindeutige Adresse in einem Listenjob – und eine Registrierungsprüfung ist eine Anfrage. Batches und Listenjobs werden vollständig angenommen oder abgelehnt, nie teilweise ausgeführt. Die Ratenbegrenzung pro Minute zählt HTTP-Aufrufe, nicht Einträge: Ein Batch mit bis zu 100 IPs oder E-Mail-Adressen zählt als eine Anfrage, während jeder Eintrag weiterhin einzeln auf das monatliche Anfragekontingent angerechnet wird. Uploads und Ergebnisse von Listenjobs werden 7 Tage nach Erstellung des Jobs gelöscht. DNS-Abfragen haben ein kurzes Zeitbudget: Schlägt eine fehl oder überschreitet sie das Zeitlimit, fällt das Ergebnis auf mx.status unknown und den Grund dns_unavailable zurück statt auf einen Fehler. Die Daten zu Wegwerf-Domains werden aus drei von der Community gepflegten Open-Source-Listen zusammengeführt, alle paar Stunden aktualisiert und um Mailserver ergänzt, die nachweislich gelistete Domains bedienen – siehe Datenquellen. Ein sehr neuer Wegwerf-Anbieter wird möglicherweise noch nicht erkannt. Alle Prüfungen erfolgen auf Domain- und Adressebene: Kein Postfach wird kontaktiert, daher belegt kein Ergebnis, dass ein Postfach existiert, wem es gehört oder dass E-Mails dort ankommen.