FÜR ENTWICKLER

API zur E-Mail-Verifizierung.

Prüfen Sie einzelne Adressen in Formularen oder verwenden Sie asynchrone Aufträge für Kundenlisten. Behalten Sie Ihren bisherigen E-Mail-Anbieter.

MIT EINER ADRESSE STARTEN

Ihre erste Anfrage.

Nutzen Sie den kostenlosen Demo-Endpunkt ohne Schlüssel. Er ist auf eine begrenzte Anfragerate beschränkt und zum Testen des Dienstes gedacht.

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

Für kostenpflichtige Prüfungen kaufen Sie ein Paket und verwenden Sie /v1/fast-verify mit Ihrem Schlüssel in X-API-Key. Halten Sie Schlüssel aus URLs, Versionsverwaltung und Analysetools heraus.

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Python-Beispiel

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Node.js-Beispiel

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

LISTE SENDEN, ERGEBNISSE ERHALTEN

Eine größere Liste prüfen.

POST /v1/tasks

Übermitteln Sie bis zu 10.000 Adressen pro Auftrag. Speichern Sie die zurückgegebene Auftrags-ID und prüfen Sie accepted, skipped und invalids: Nicht jede Eingabe wird zwangsläufig eingereiht. Duplikate, fehlerhaft formatierte und gesperrte Adressen können entfernt werden; bei geringem Guthaben kann die Liste nur teilweise angenommen werden.

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

Fragen Sie den Status ab und laden Sie dann jede Ergebnisseite. Eine Antwort mit ausschließlich ungültigen Eingaben kann eine leere Auftrags-ID enthalten; fragen Sie diese nicht ab.

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Ergebnisse abgeschlossener Aufträge liegen als JSON vor. Laden Sie weitere Seiten, bis die gesamte angenommene Liste abgerufen wurde. Für eine automatische Benachrichtigung bei Abschluss übergeben Sie einen Webhook mit mode: "completed" beim Erstellen des Auftrags.

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

Prüfen Sie im Schema die Webhook-Konfiguration und Signaturprüfung, bevor Sie ihn produktiv aktivieren.

DIE ANTWORT VERSTEHEN

Format bedeutet nicht Existenz.

Dies sind getrennte Signale. Eine korrekt formatierte Adresse kann trotzdem nicht existieren, temporär oder nicht bestätigbar sein.

Feld	Bedeutung
`valid`	Die Adresse hat die Syntaxprüfung bestanden. Das allein bestätigt ihr Postfach nicht.
`exists`	Das Ergebnis der Postfachprüfung. Interpretieren Sie es zusammen mit Fehlern und Catch-all-Signalen.
`disposable`	Die Domain wurde als Anbieter temporärer E-Mail-Adressen erkannt.
`accept_all`	Der Server akzeptiert beliebige Adressen; das konkrete Postfach lässt sich nicht zuverlässig bestätigen.
`error_category`	Erklärt einen Fehler oder ein Risiko, etwa no_mx, risky oder ein vorübergehendes Serverproblem.
`permanent_error`	Bei der Prüfung wurde ein dauerhafter Fehler zurückgegeben. Ein vorübergehender Fehler darf nicht als dauerhafte Ablehnung gewertet werden.
`ttl`	Ein Hinweis zur Wartezeit für erneute Versuche oder zum Cache, in Sekunden, sofern zurückgegeben.

Die Verifizierung garantiert keine Zustellung, verhindert nicht alle Beschwerden und weist kein Eigentum an einem Postfach nach.

Kennen Sie Ihr Guthaben.

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Die Antwort enthält verbleibendes, reserviertes und verbrauchtes Guthaben, Schlüsseltyp und Ablaufdatum. Eine Standardverifizierung verbraucht eine Guthabeneinheit; tatsächliche Filterung und Abrechnung hängen vom Endpunkt und der Auftragsannahme ab. Prüfen Sie die Antwort, bevor Sie eine vollständig hochgeladene Liste als verarbeitet betrachten.

Eine Antwort mit Status 429 bedeutet, dass Anfragen begrenzt werden. Warten Sie vor einem erneuten Versuch. Andere Fehler können in der aktuellen API als JSON oder Text zurückgegeben werden; interpretieren Sie HTTP-Fehler nicht als Verifizierungsergebnisse.

Die Verifizierungsspezifikation.

OpenAPI-JSON herunterladen

Die öffentliche Spezifikation umfasst Demo, Schnellprüfung, Aufträge, Auftragsstatus, Ergebnisse und Kontoguthaben. Versand- und Verwaltungsendpunkte sind nicht Teil dieser Verifizierungsreferenz.

Brauchen Sie Hilfe bei der Anbindung Ihrer Plattform? support@zbounce.net