> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# E-Mail-Validierungs-API

> Verbessern Sie die Zustellbarkeit und halten Sie Ihre Mailinglisten sauber mit der branchenführenden E-Mail-Validierungs-API von Cleariflow.

## Schnellstart

Für eine Anfrage benötigen Sie nur Ihren eindeutigen `api_key` und die zu prüfende `email` — mehr ist nicht erforderlich:

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = jane.doe@acme-corp.com
```

Bei Erfolg liefert die Anfrage alle verfügbaren Erkenntnisse zur Adresse:

<ResponseExample>
  ```json theme={"system"}
  {
    "email": "jane.doe@acme-corp.com",
    "autocorrect": "",
    "deliverability": "DELIVERABLE",
    "quality_score": 0.85,
    "is_valid_format": {
      "value": true,
      "text": "TRUE"
    },
    "is_free_email": {
      "value": false,
      "text": "FALSE"
    },
    "is_disposable_email": {
      "value": false,
      "text": "FALSE"
    },
    "is_role_email": {
      "value": false,
      "text": "FALSE"
    },
    "is_catchall_email": {
      "value": false,
      "text": "FALSE"
    },
    "is_mx_found": {
      "value": true,
      "text": "TRUE"
    },
    "is_smtp_valid": {
      "value": true,
      "text": "TRUE"
    }
  }
  ```
</ResponseExample>

### Anfrageparameter

<ParamField query="api_key" type="string" required>
  Ihre persönlichen API-Zugangsdaten. Schlüssel sind pro Cleariflow-Produkt begrenzt — ein
  E-Mail-Validierungsschlüssel berechtigt z. B. nicht zu Anfragen an die IP-Geolokalisierungs-API.
</ParamField>

<ParamField query="email" type="String" required>
  Die zu prüfende E-Mail-Adresse.
</ParamField>

<ParamField query="auto_correct" type="Boolean">
  Optionales Flag zum Deaktivieren der Autokorrektur. Setzen Sie `auto_correct=false`, um sie
  auszuschalten. Standardmäßig ist sie aktiviert.
</ParamField>

### Antwortparameter

Antworten werden als kompaktes, standardisiertes [JSON](https://www.json.org/json-en.html) zurückgegeben.

<ResponseField name="email" type="String">
  Gibt die in der Anfrage übermittelte `email` zurück.
</ResponseField>

<ResponseField name="auto_correct" type="String">
  Vorgeschlagene Korrektur, wenn ein wahrscheinlicher Tippfehler erkannt wird (z. B.
  [johnsmith@gmial.com](mailto:johnsmith@gmial.com) => [johnsmith@gmail.com](mailto:johnsmith@gmail.com)). Leer, wenn kein Vorschlag vorliegt.
</ResponseField>

<ResponseField name="deliverability" type="String">
  Cleariflows Einschätzung, ob die Adresse E-Mails empfangen kann. Mögliche
  Werte: `DELIVERABLE`, `UNDELIVERABLE`, `UNKNOWN`. `DELIVERABLE` erfordert eine
  erfolgreiche SMTP-Prüfung; wenn MX-Einträge vorhanden sind, SMTP das Postfach aber
  nicht bestätigen kann (häufig bei großen Anbietern), ist das Ergebnis `UNKNOWN`.
  Alle Pläne führen dieselben Prüfungen aus; Free-Pläne unterscheiden sich nur in
  monatlichem Kontingent und Ratenlimit (siehe Fehlercodes 422 und 429).
</ResponseField>

<ResponseField name="quality_score" type="Float">
  Dezimalwert von `0` bis `0.99` für die Adressqualität. Disposable-Adressen sind auf
  etwa `0.05` begrenzt; ohne SMTP-Bestätigung maximal `0.55`.
</ResponseField>

<ResponseField name="is_valid_format" type="Boolean">
  `true`, wenn die Adresse dem Standardmuster `local@domain.tld` entspricht.
  Fehlende Elemente oder ungültige Zeichen ergeben `false`.
</ResponseField>

<ResponseField name="is_free_email" type="Boolean">
  `true`, wenn die Domain zu einem kostenlosen E-Mail-Anbieter gehört (z. B. Gmail, Yahoo).
</ResponseField>

<ResponseField name="is_disposable_email" type="Boolean">
  `true`, wenn die Domain auf unserer Liste temporärer Wegwerf-Postfach-Anbieter steht
  (z. B. Mailinator, Yopmail).
</ResponseField>

<ResponseField name="is_role_email" type="Boolean">
  `true`, wenn der lokale Teil wie ein Funktionspostfach und nicht wie eine Einzelperson wirkt,
  z. B. `team@`, `sales@`, `info@`.
</ResponseField>

<ResponseField name="is_catchall_email" type="Boolean">
  `true`, wenn die Domain als
  [Catch-all](https://www.corporatecomm.com/faqs/other-questions/what-is-a-catch-all-account) konfiguriert ist.
</ResponseField>

<ResponseField name="is_mx_found" type="Boolean">
  `true`, wenn [MX-Records](https://en.wikipedia.org/wiki/MX_record) für die
  Domain existieren.
</ResponseField>

<ResponseField name="is_smtp_valid" type="Boolean">
  `true`, wenn die
  [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol)-Verifizierung erfolgreich ist.
  Schlägt SMTP fehl, andere Prüfungen aber bestehen, kann das Ergebnis `UNKNOWN` sein.
  Wir raten davon ab, Registrierungen oder Formularübermittlungen allein aufgrund von
  SMTP-Fehlern zu blockieren.
</ResponseField>

## Anfragebeispiele

### Beispiel: wahrscheinlicher Tippfehler

Dieses Beispiel zeigt eine Anfrage, bei der in der übermittelten Adresse ein wahrscheinlicher Tippfehler erkannt wird.

Auch wenn ein wahrscheinlicher Tippfehler gefunden wird, werden alle weiteren Prüfungen (z. B. kostenlose E-Mail,
Wegwerf-Domain) gegen die ursprünglich übermittelte Adresse durchgeführt — nicht gegen den vorgeschlagenen Korrekturvorschlag.

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith@gmial.con
```

Eine erfolgreiche Antwort sieht so aus:

```json theme={"system"}
{
  "email": "johnsmith@gmial.con",
  "autocorrect": "johnsmith@gmail.com",
  "deliverability": "UNKNOWN",
  "quality_score": 0.4,
  "is_valid_format": {
    "value": true,
    "text": "TRUE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": false,
    "text": "FALSE"
  },
  "is_smtp_valid": {
    "value": false,
    "text": "FALSE"
  }
}
```

### Beispiel: ungültiges Format

Dieses Beispiel zeigt eine Adresse, die die grundlegende Formatprüfung nicht besteht. Wenn
`is_valid_format` `false` ist, werden nachfolgende Prüfungen (z. B. `is_free_email`,
`is_role_email`) übersprungen und als `false` gemeldet.

```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith
```

Eine erfolgreiche Antwort sieht so aus:

```json theme={"system"}
{
  "email": "johnsmith",
  "autocorrect": "",
  "deliverability": "UNDELIVERABLE",
  "quality_score": 0.0,
  "is_valid_format": {
    "value": false,
    "text": "FALSE"
  },
  "is_free_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_disposable_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_role_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_catchall_email": {
    "value": false,
    "text": "FALSE"
  },
  "is_mx_found": {
    "value": false,
    "text": "FALSE"
  },
  "is_smtp_valid": {
    "value": false,
    "text": "FALSE"
  }
}
```

## Massen-Upload (CSV)

Möchten Sie die API nicht direkt aufrufen? Nutzen Sie den CSV-Massen-Upload — die Ergebnisse werden
Ihnen per E-Mail zugestellt, sobald die Verarbeitung abgeschlossen ist.

Beim CSV-Upload beachten Sie bitte:

* E-Mail-Adressen in die erste Spalte eintragen.
* Leere Zeilen entfernen.
* Eine Adresse pro Zeile verwenden.
* Dateien auf maximal 50.000 Zeilen begrenzen.

## Antwort- und Fehlercodes

Fehler werden als JSON mit Code und lesbarer Beschreibung zurückgegeben. Häufige
Codes sind unten aufgeführt.

| Code | Typ                   | Beschreibung                                                                                  |
| ---- | --------------------- | --------------------------------------------------------------------------------------------- |
| 200  | OK                    | Anfrage erfolgreich abgeschlossen.                                                            |
| 400  | Bad request           | Fehlerhafte oder ungültige Anfrage.                                                           |
| 401  | Unauthorized          | Authentifizierung fehlgeschlagen — in der Regel fehlt der API-Schlüssel oder er ist ungültig. |
| 422  | Quota reached         | Kontingent erschöpft (z. B. unzureichendes Guthaben bei kostenlosen Tarifen).                 |
| 429  | Too many requests     | Ratenlimit überschritten (kostenlose Tarife: maximal 1 Anfrage/Sekunde).                      |
| 500  | Internal server error | Unerwarteter Fehler auf unserer Seite.                                                        |
| 503  | Service unavailable   | Dienst vorübergehend nicht verfügbar.                                                         |

## Weitere Hinweise

Hinweis zu Tarifen: Alle Pläne (kostenlos und kostenpflichtig) führen dieselben Validierungsprüfungen aus, einschließlich MX-, SMTP- und Catch-all-Erkennung.

Hinweis zur Abrechnung: Jede geprüfte E-Mail verbraucht ein Guthaben pro Anfrage — unabhängig vom
Ergebnis. Die Übermittlung einer ungültigen Adresse (z. B. „fda3346ds") zählt ebenfalls als ein
Guthaben.