JSON-Schnittstelle

Die Schnittstelle bildet denselben Ablauf ab wie die Weboberfläche: Adresse anfordern, Nachricht dorthin senden, Ergebnis abholen. Sie ist bewusst klein gehalten – drei Endpunkte genügen dafür.

Anmeldung

Jede Anfrage trägt einen API-Schlüssel in der Kopfzeile Authorization. Den Schlüssel erzeugen Sie in Ihrem Kundenkonto; er wird nur ein einziges Mal angezeigt.

Authorization: Bearer mc_…

Wenn Ihr Werkzeug diese Kopfzeile nicht setzen kann, wird ersatzweise X-Api-Key akzeptiert.

Guthaben

Ein Guthabenpunkt wird beim Anfordern der Testadresse abgebucht, nicht erst bei der Auswertung. Andernfalls ließe sich das Guthaben umgehen, indem man beliebig viele Adressen anfordert und nur einen Teil davon benutzt. Fordern Sie also nur an, was Sie auch senden.

Endpunkte

Testadresse anfordern

POST https://mail-checker.de/api/v1/tests

Antwort (Status 201):

{
  "ok": true,
  "test": {
    "token": "a1b2c3…",
    "adresse": "test-xxxxxxxxxxxx@srv1.mail-checker.de",
    "gueltig_bis": "2026-08-18T15:20:00+02:00",
    "gueltig_fuer_sekunden": 600,
    "status_url": "https://mail-checker.de/api/v1/tests/a1b2c3…",
    "bericht_url": "https://mail-checker.de/result/a1b2c3…"
  },
  "guthaben": 49
}

Stand und Ergebnis abholen

GET https://mail-checker.de/api/v1/tests/{token}

Solange noch nichts eingegangen ist, antwortet der Endpunkt mit Status 202 und "status": "wartet"; während der Auswertung mit "analysiere". Erst danach steht das vollständige Ergebnis mit Status 200 bereit.

Fragen Sie höchstens alle fünf Sekunden nach. Eine Auswertung dauert in der Regel unter zwanzig Sekunden.

Konto abfragen

GET https://mail-checker.de/api/v1/konto

Liefert Guthaben, Gesamtverbrauch und die zehn letzten Tests. Nützlich, um zu prüfen, ob ein Schlüssel gültig ist.

Fehler

Fehler haben immer dieselbe Form:

{
  "ok": false,
  "fehler": {
    "kennung": "guthaben_leer",
    "text": "Das Guthaben ist aufgebraucht."
  }
}

Status	Kennung	Bedeutung
401	kein_schluessel	Kopfzeile fehlt
401	schluessel_ungueltig	unbekannt oder zurückgezogen
402	guthaben_leer	keine Tests mehr verfügbar
404	test_unbekannt	Kennung gehört nicht zu Ihrem Konto
405	verfahren_nicht_erlaubt	falsches HTTP-Verfahren
429	zu_viele_anfragen	600 Anfragen je Schlüssel und Stunde

Ein vollständiger Durchlauf

SCHLUESSEL="mc_…"

# 1. Adresse anfordern
ANTWORT=$(curl -s -X POST \
  -H "Authorization: Bearer $SCHLUESSEL" \
  https://mail-checker.de/api/v1/tests)

TOKEN=$(echo "$ANTWORT" | jq -r .test.token)
ADRESSE=$(echo "$ANTWORT" | jq -r .test.adresse)

# 2. Nachricht an $ADRESSE senden (mit Ihrem eigenen Mailversand)

# 3. Ergebnis abholen
curl -s -H "Authorization: Bearer $SCHLUESSEL" \
  https://mail-checker.de/api/v1/tests/$TOKEN | jq .

Ein Konto legt derzeit die Betreiberin an. Schreiben Sie an info@mx-its.de, wenn Sie die Schnittstelle nutzen möchten.