API-Nutzung

Spamexx stellt eine HTTP-API bereit, mit der Sie programmatisch prüfen können:

Threat-Lookup – einen Indikator (Domain, E-Mail, IP, URL oder Hash) gegen die Spamexx-Bedrohungsdatenbank abfragen.
Content-Prüfung – eine Nachricht durch die Spam- und Virenprüfung laufen lassen und ein Verdikt erhalten.
Tariflimits & Verbrauch – die Limits Ihrer gebuchten Tarife und den aktuellen Verbrauch abfragen (ohne Kontingent-Verbrauch).

Basis-URL: https://api.spamexx.com

Authentifizierung

Erstellen Sie einen API-Key unter Einstellungen → API-Keys. Der Schlüssel wird aus Sicherheitsgründen nur einmal angezeigt – bewahren Sie ihn sicher auf.

Die API-Key-Verwaltung: Kontingent/Rate, Liste der Schlüssel mit Status und „Key erstellen".

Senden Sie ihn bei jeder Anfrage im Authorization-Header:

user@spamexx:~$cat example.txt

Authorization: Bearer sx_ihr_schluessel

Kontingent (Anfragen/Monat) und Rate-Limit (Anfragen/Minute) richten sich nach Ihrem API-Tarif. Ohne gebuchten API-Tarif gilt die kostenlose Stufe. Den aktuellen Verbrauch sehen Sie unter Einstellungen → API-Keys.

Threat-Lookup

POST /api/v1/check/lookup

Anfrage-Body:

user@spamexx:~$cat example.json

{ "type": "domain", "value": "beispiel.de" }

type ist eines von domain, email, ip, url, hash.

Antwort:

user@spamexx:~$cat example.json

{ "verdict": "clean", "score": 0.0, "matched": false }

verdict – clean, suspicious oder spam
score – Reputationswert zwischen 0 und 1
matched – ob ein Treffer in der Bedrohungsdatenbank vorlag

Beispiel:

user@spamexx:~$cat example.txt

curl -X POST https://api.spamexx.com/api/v1/check/lookup \
  -H "Authorization: Bearer sx_ihr_schluessel" \
  -H "Content-Type: application/json" \
  -d '{"type":"url","value":"http://verdaechtige-domain.example/pfad"}'

Content-Prüfung

POST /api/v1/check/message

Senden Sie entweder die komplette Roh-Mail oder einzelne Felder.

Komplette Mail (empfohlen – mit allen Headern für die genaueste Bewertung):

user@spamexx:~$cat example.json

{ "raw": "<RFC-822-Mail als Text oder Base64>" }

Einzelne Felder:

user@spamexx:~$cat example.json

{ "from": "absender@example.com", "subject": "Betreff", "body": "Text der Nachricht", "source_ip": "203.0.113.5" }

Hinweis: Für ein korrektes Ergebnis senden Sie möglichst die vollständige Roh-Mail mit Headern. Eine minimale Nachricht ohne Header kann allein wegen fehlender Standard-Header höher bewertet werden.

Antwort:

user@spamexx:~$cat example.json

{ "verdict": "deliver", "score": 2.1, "is_spam": false, "is_virus": false }

verdict – deliver, quarantine (Spam) oder reject (Virus)
score – aggregierter Prüf-Score
is_spam / is_virus – Klassifikations-Flags

Der eingesandte Inhalt wird nur kurzzeitig geprüft und niemals gespeichert oder protokolliert.

Tariflimits & Verbrauch

GET /api/v1/limits

Liefert die Ihrem API-Key zugeordneten Tariflimits je Produktlinie samt aktuellem Verbrauch. Dieser Abruf verbraucht KEIN Kontingent (eigenes Limit 60/min) – ideal, um vor einem Lauf das Restkontingent zu prüfen oder es in Ihrer App anzuzeigen.

user@spamexx:~$cat example.txt

curl https://api.spamexx.com/api/v1/limits \
  -H "Authorization: Bearer sx_ihr_schluessel"

Antwort (nicht gebuchte Linien werden weggelassen):

user@spamexx:~$cat example.json

{
  "tenant_id": "…",
  "period": "2026-06",
  "unlimited": false,
  "api":   { "plan": "Community", "requests": { "used": 0, "max": 5000 }, "remaining": 5000, "rate_per_min": 10 },
  "saas":  { "plan": "Enterprise", "domains": { "used": 1, "max": 50 }, "mailboxes": { "used": 6, "max": 500 }, "retention_days": 365 },
  "spool": { "plan": "Basic", "domains": { "used": 0, "max": 3 }, "spool_retention_hours": 72 }
}

api – API-Kontingent: requests.used / requests.max (Monat), remaining, rate_per_min.
saas – Online/SaaS: domains und mailboxes jeweils used / max, retention_days.
spool – Backup/Failover: domains (used / max), spool_retention_hours.
max: 0 bedeutet unbegrenzt; unlimited: true hebt alle Limits auf; period ist der Abrechnungs-Monat des Verbrauchszählers.

Hinweis: Die verbindliche Durchsetzung des Kontingents erfolgt weiterhin an den Check-Endpunkten (429 bei Erschöpfung). Die hier gemeldeten Verbrauchswerte sind informativ.

Fehler & Grenzen

401 – Schlüssel fehlt, ist ungültig oder widerrufen.
429 – Rate-Limit (Anfragen/Minute) oder Monats-Kontingent erreicht.
503 – Prüfung vorübergehend nicht verfügbar (Anfrage später wiederholen).

Brauchen Sie mehr Kontingent? Wechseln Sie Ihren API-Tarif oder stellen Sie sich unter Abrechnung einen individuellen Tarif zusammen.