Prüfen Sie E-Mail-Adressen über eine REST-API

Senden Sie die Anfrage von Ihrem Server

Erstellen Sie in Ihrem Emvero-Konto einen API-Schlüssel. Ihr Server sendet die Adresse an den Endpunkt und übergibt den Schlüssel zur Bearer-Authentifizierung. Bewahren Sie ihn auf dem Server auf, damit er nicht im Browsercode zugänglich ist.

Die folgende Anfrage verwendet die vollständige Prüfung, die standardmäßig ausgewählt ist. Der Header Idempotency-Key ordnet Wiederholungen demselben Vorgang zu: Wird die Anfrage etwa nach einem Netzwerkfehler erneut gesendet, startet innerhalb des vorgesehenen Zeitfensters keine zweite Prüfung.

curl -sS https://api.emvero.tech/v1/verifications \
  -H "Authorization: Bearer emv_your_credential" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-8f21c0" \
  -d '{"email":"ada@example.com"}'

Das folgende Beispiel zeigt eine HTTP-200-Antwort. Adresse, Prüfkennung und Belege sind frei gewählte Beispielwerte; es wurde keine aktuelle Prüfung von example.com durchgeführt:

{
  "id": "5f0b6f3e-1a4c-4a1f-9d2e-8f7b3c2a1d90",
  "email": "ada@example.com",
  "normalized": { "domain": "example.com", "ascii_domain": "example.com" },
  "status": "deliverable",
  "confidence": 0.92,
  "action": "allow",
  "checks": {
    "syntax": "valid",
    "domain": "valid",
    "mail_routing": "valid",
    "smtp": "accepted",
    "accept_all": "no",
    "disposable": false,
    "role_account": false,
    "public_provider": false,
    "smtp_utf8_required": false
  },
  "reason_codes": ["MX_FOUND", "SMTP_RCPT_ACCEPTED"]
}

HTTP 200 bedeutet, dass die Anfrage erfolgreich bearbeitet wurde. Ob die Adresse zustellbar ist, steht im JSON-Ergebnis. Deshalb kommt auch undeliverable mit HTTP 200 zurück. HTTP-Fehler betreffen dagegen die Anfrage, den Schlüssel, das Guthaben, ein Nutzungslimit oder den Dienst.

Unterscheiden Sie Ergebnis und Handlungsempfehlung

Das Feld status hat vier abschließende Werte: deliverable, risky, undeliverable und unknown. pending zeigt an, dass die Prüfung noch läuft. Die Tabelle nennt die Bedeutung und die möglichen Empfehlungen:

Die Empfehlung steht separat in action: allow bedeutet zulassen, allow_with_email_confirmation bedeutet mit E-Mail-Bestätigung fortfahren und reject bedeutet ablehnen. Eine Adresse kann etwa risky sein und dennoch die Empfehlung allow erhalten. Lesen Sie daher den zurückgegebenen Wert, statt die Aktion allein aus dem Status abzuleiten. Die API führt diese Schritte nicht selbst aus; Ihre Anwendung entscheidet, wie sie die Empfehlung umsetzt.

Die übrigen Felder erklären das Ergebnis. checks enthält die Ergebnisse der einzelnen Prüfstufen und zusätzliche Risikosignale. In reason_codes stehen maschinenlesbare Kennungen: DISPOSABLE_DOMAIN weist auf eine bekannte Domain für temporäre Postfächer hin, SMTP_RCPT_ACCEPTED auf die Annahme des Empfängers durch den Mailserver.

confidence bewertet die Stärke der Belege auf einer Skala von 0 bis 1. Der Wert gibt keine Wahrscheinlichkeit für die Zustellung oder das Eintreffen im Posteingang an. Die Seite zur Prüfung einer einzelnen Adresse erläutert, was Adressformat, Mailweg und SMTP-Prüfung jeweils aussagen können.

Rufen Sie das Ergebnis einer laufenden Prüfung ab

Bei einer vollständigen Prüfung liegen die Belege zum Empfänger nicht immer sofort vor. Die API kann dann zunächst pending zurückgeben. Dieser Wert kennzeichnet eine laufende Prüfung und ist kein fünftes abschließendes Ergebnis. Die Antwort enthält die bereits gesammelten Belege, die Prüfkennung id und das empfohlene Warteintervall retry_after_ms in Millisekunden. Der folgende Ausschnitt zeigt die Felder für den späteren Abruf:

{
  "id": "5f0b6f3e-1a4c-4a1f-9d2e-8f7b3c2a1d90",
  "status": "pending",
  "retry_after_ms": 2000
}

Warten Sie das angegebene Intervall ab und rufen Sie anschließend GET /v1/verifications/{id} mit demselben Bearer-Schlüssel auf. Verwenden Sie dabei die Prüfkennung aus der Antwort. Solange der Status pending lautet, fragen Sie nach dem jeweiligen Warteintervall erneut ab. Sobald die Prüfung abgeschlossen ist, erhalten Sie das abschließende Ergebnis über denselben Abruf. Die API sendet keinen Callback.

Legen Sie für Ihren Ablauf eine maximale Wartezeit fest, besonders wenn eine Person auf die Antwort eines Formulars wartet. Läuft diese Frist ab, ist die Adresse damit weder als ungültig noch als nicht zustellbar eingestuft. Die Dokumentation zu laufenden Prüfungen beschreibt den Abruf im Detail.

Wählen Sie die Prüftiefe und behandeln Sie HTTP-Fehler

Wenn Sie variant weglassen, verwendet die API full. Mit "variant":"domain" wählen Sie eine Domain-Prüfung: Sie untersucht das Adressformat, die Domain über DNS und den Mailweg, ohne eine SMTP-Sitzung zu öffnen. Beide Prüftiefen verwenden denselben Endpunkt und dieselben Ergebnisfelder.

Eine Domain-Prüfung kann nicht feststellen, ob ein bestimmtes Postfach existiert. Auch eine vollständige Prüfung kann mit unknown enden, etwa bei einem Timeout oder wenn der Mailserver keine eindeutige Auskunft zum Empfänger gibt.

Bei HTTP 400 müssen Sie die Anfrage korrigieren. 401 weist auf einen fehlenden oder ungültigen Schlüssel hin, 402 auf unzureichendes Credit-Guthaben. Reduzieren Sie bei 429 die Anfragehäufigkeit und beachten Sie Retry-After, sofern der Header vorhanden ist. Ein Fehler mit 5xx liefert kein verlässliches Prüfergebnis zur Adresse. Behalten Sie bei einer Wiederholung desselben Vorgangs den Idempotenzschlüssel bei.

Der Schnellstart zeigt die Integration Schritt für Schritt. Die Fehlerreferenz erläutert die einzelnen HTTP-Antwortcodes.

Für die Prüfung während einer Formulareingabe beschreibt die Seite zur Echtzeit-Verifizierung den Ablauf. Wenn Sie eine vorhandene Liste prüfen möchten, erläutert die Seite zur Bulk-Verifizierung, wie Ihre Anwendung eine Anfrage pro Adresse sendet und die Ergebnisse speichert. Emvero bietet dafür keinen gehosteten CSV-Upload und keinen separaten Batch-Endpunkt.