Achtung: Umstellung auf SSL

Mit der Änderung zum 1. April unterstützt die Schnittstelle ausschließlich Anfragen, die über HTTPS gestellt sind. Dazu leitet die Schnittstelle bereits auf das sichere Protokoll um. Bitte passen Sie Ihre Skripte intern insoweit an, als dass Sie das HTTPS Protokoll als URL nutzen. Anderweitig wird Ihnen eine leere Rückmeldung zurückgegeben.

Mehr dazu hier: Vollständige Umstellung auf HTTPS

Wichtig!

Da wir unser Angebot stetig weiterentwickeln, kann es vorkommen, dass einige Informationen auf dieser Unterseite nicht mehr aktuell sind. Wir sind allerdings bemüht, die Art und Weise wie Sie unsere Schnittstelle nutzen nicht zu beeinträchtigen.

Sollten dennoch größere Änderungen vorgenommen werden, wird dies entsprechend kommuniziert.

Grundsätzlich

Alle Anfragen an die Schnittstelle müssen an die Adresse https://api.block-trashmail.de gestellt werden. Da die Verbindung durch Nutzung von HTTPS und durch Einsatz eines SSL Zertifikats von Let's Encrypt verschlüsselt wird, ist der Austausch der Informationen sicher. Bitte beachten Sie, dass wir alle Verbindungsversuche über HTTP zwingend auf HTTPS umleiten. Nutzen Sie daher einen modernen Browser, um sicherzustellen, dass Sie die Schnittstelle weiterhin erreichen können. Eine Übersicht, welche Geräte / Software die Zertifikate von Let's Encrypt unterstützt, finden Sie hier: https://letsencrypt.org/docs/certificate-compatibility/

Damit Ihre Anfrage verarbeitet werden kann, ist die Angabe des API-Schlüssels zwingend erforderlich. Sie müssen sich daher bei jeder Anfrage mittels der HTTP-Authentifizierung authentifizieren.

Wir verwenden in dieser Anleitung ed076287532e86365e841e92bfc50d8c als Beispiel für den API-Schlüssel. Sie müssen an der Stelle Ihren eigenen API-Schlüssel einsetzen.

Erfolgreiche Rückgabe

{
  "error": false,
  "results": {
    "parameter": "value"
  }
}
 

Erklärung

Bei einer erfolgreichen Abfrage treten logischerweise keine Fehlermeldungen auf und so wird hier error entsprechend auf false gesetzt. Außerdem werden results die Rückgabewerte der abgefragten Funktion zugewiesen.

Dabei kann es sich um einzelne Werte handeln oder um Gruppierungen (Arrays). Beispiele dafür finden Sie weiter unten.

Fehlerhafte Rückgabe

{
    "error": {
        "code": (integer),
        "message": (string)
    },
    "results": null
}

Erklärung

Im Fehlerfall werden die detaillierten Angaben zum Fehler in error geschrieben. Neben dem Fehlercode (Zahl) finden Sie dort auch den Fehlertext (Zeichenkette) wieder. Wir halten uns hierbei am Standard für HTTP-Statuscodes.

Einfache Abfrage

Führt eine einfache Abfrage für eine Domain oder vollwertige E-Mail Adresse aus und liefert das Ergebnis.

Befehl (Konsole)

curl --user ed076287532e86365e841e92bfc50d8c:X https://api.block-trashmail.de/check/example.com

Legende

Funktion Parameter
/check/ akzeptiert wird eine Domain in Form von example.com oder eine valide E-Mail Adresse

Rückgabe

Parameter Wert
listed true wenn gelistet, ansonsten false

Beispiel

{
    "error": false,
    "results": {
        "listed": false
    }
}
Volumen ermitteln

Ermittelt den aktuellen Verbrauch und gibt diesen zusammen mit den Limits zurück.

Befehl (Konsole)

curl --user ed076287532e86365e841e92bfc50d8c:X https://api.block-trashmail.de/quota

Legende

Funktion Parameter
/quota/ -

Rückgabe

Parameter Wert
quota Gruppe A: Verbrauch
   hourly … in den letzten 60 Minuten
   daily … in den letzten 24 Stunden
   monthly … in den letzten 30 Tagen
limits * Gruppe B: maximale Anfragen
   hourly … je 60 Minuten
   daily … je 24 Stunden
   monthly … je 30 Tage, entspricht zugewiesenem Gesamtvolumen (Standard: 500)

* Um mehr über die Limits zu erfahren, lesen Sie bitte folgendes: Welche Beschränkungen gibt es bei der Schnittstelle?

Beispiel

{
    "error": false,
    "results": {
        "quota": {
            "hourly": 1,
            "daily": 1,
            "monthly": 26
        },
        "limits": {
            "hourly": 25,
            "daily": 75,
            "monthly": 500
        }
    }
}
Letzte Abfragen ausgeben

Zeigt die letzten zehn Abfragen an und den Zeitpunkt der Abfrage samt Ergebnis.

Befehl (Konsole)

curl --user ed076287532e86365e841e92bfc50d8c:X https://api.block-trashmail.de/latest

Legende

Funktion Parameter
/latest/ -

Rückgabe

Parameter Wert
latest Arrays im folgenden Format: Domain, Zeitpunkt, Ergebnis

Beispiel

{
    "error": false,
    "results": {
        "latest": [
            [
                "example.com",
                1451930390,
                false
            ],
            [
                "example.com",
                1450206778,
                false
            ],
            [
                "example.com",
                1450206769,
                false
            ],
            [
                "example.com",
                1450206756,
                false
            ],
            [
                "example.com",
                1450206737,
                false
            ],
            [
                "example.com",
                1450206722,
                false
            ],
            [
                "example.com",
                1450206718,
                false
            ],
            [
                "example.com",
                1450206716,
                false
            ],
            [
                "example.com",
                1450206713,
                false
            ],
            [
                "example.com",
                1450206711,
                false
            ]
        ]
    }
}
Einfachste Variante mit cURL
<?php
// cURL Handle initiieren
$curl = curl_init();

// Variablen setzen
$apikey = '';
$url = 'https://api.block-trashmail.de';
$email = 'foobar@example.com';

// Einstellungen setzen
curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_USERPWD => $apikey . ':X',
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_URL => $url . '/check/'. $email,
));

// Anfrage senden und Rückgabewert zwischenspeichern
$res = curl_exec($curl);

// JSON in PHP Array umwandeln
$data = json_decode($res, true);

// Anfrage auf Fehler prüfen
if (empty($data['error'])) {
 // Ergebnis verwerten
 if (true == $data['results']['listed']) {
  echo $email . ' ist eine Wegwerf E-Mail Adresse';
 } else {
  echo $email . ' ist KEINE Wegwerf E-Mail Adresse';
 }
} else {
 // Fehler ausgeben
 echo 'Ein Fehler ist aufgetreten: '. $data['error']['message'];
}

// Initiierung von cURL auflösen (Speicherplatz bereinigen)
curl_close($curl);
?>
Alternative mit file_get_contents()

Wenn Ihnen cURL nicht zur Verfügung steht können Sie auch file_get_contents() nutzen.

<?php
// Variablen setzen
$apikey = '';
$url = 'https://api.block-trashmail.de';
$email = 'foobar@example.com';

// Daten für Zugriffsberechtigung setzen
$context = stream_context_create(array(
    'http' => array(
        'header'  => 'Authorization: Basic' . base64_encode($apikey . ':X')
    )
));

// Anfrage senden und Rückgabewert zwischenspeichern
$res = file_get_contents($url . '/check/'. $email, false, $context);

// JSON in PHP Array umwandeln
$data = json_decode($res, true);

// Anfrage auf Fehler prüfen
if (empty($data['error'])) {
    // Ergebnis verwerten
    if (true == $data['results']['listed']) {
        echo $email . ' ist eine Wegwerf E-Mail Adresse';
    } else {
        echo $email . ' ist KEINE Wegwerf E-Mail Adresse';
    }
} else {
    // Fehler ausgeben
    echo 'Ein Fehler ist aufgetreten: '. $data['error']['message'];
}
?>

Statuscodes

Fehlercode Fehlertext Erklärung
200 OK -
400 Fehlerhafte Anfrage Die Anfrage an die API-Schnittstelle wurde falsch oder nicht vollständig gestellt. Beispiel: Es wurde als Method POST genutzt, obwohl nur GET zulässig ist.
401 Autorisierung erforderlich Anfrage an einen geschützten Bereich innerhalb der API, z.B. für die Abfrage von Domains. Der API-Schlüssel wurde entweder nicht oder falsch übergeben.
403 Zugriff verweigert Der Zugriff auf die API-Schnittstelle wurde verweigert. Der API-Schlüssel ist ungültig oder wurde widerrufen.
404 Nicht gefunden -
408 Zeitüberschreitung Überschreitung der Zeit für eine Anfrage. Aus Sicherheitsgründen müssen manche Prozesse in einer bestimmten Zeitspanne abgewickelt werden.
429 Limit innerhalb eines bestimmten Zeitraums überschritten Das Limit an Abfragen pro Stunde, Tag oder Monat ist aufgebraucht.
500 Interner Serverfehler -
503 Service nicht verfügbar API-Schnittstelle kurzfristig nicht erreichbar, z.B. bei Wartungsarbeiten
Durch die weitere Nutzung unserer Webseite stimmen Sie der Verwendung von Cookies zur Gewährleistung des reibungslosen Ablaufs Ihres Besuchs und zur Erstellung von Besucherstatistiken zu. Weiterlesen …