Integration

REST-API — alles was die UI kann.

MailGuard ist API-first gebaut. Jede Funktion im Web-UI ist auch über REST-Endpoint erreichbar — Domain-Verwaltung, Quarantäne-Aktionen, Lizenz-Status, Audit-Log-Export, Reporting. OpenAPI-Spec als versionierter Vertrag, API-Keys mit Scope und Rate-Limit, Webhook-Hooks für Real-Time-Integrationen.

Authentifizierung

Zwei Wege parallel:

  • Cookie-Session — wenn die UI selbst gegen die API arbeitet (Browser-basiert, CSRF-geschützt)
  • X-API-Key Header — für externe Integrationen (CI/CD, SIEM, Monitoring, Custom-Apps)

API-Keys haben das Format nmg_ + 64 Hex-Zeichen. Bei der Erstellung einmalig der volle Key zurückgegeben — danach in der DB nur noch der Hash plus erste 20 Zeichen für UI-Anzeige. Lost-Key-Recovery: nicht möglich, neuen erstellen und alten revoken.

Scopes pro API-Key

Pro Key konfigurierbar:

  • read-only — alle GET-Endpoints, keine Schreib-Operationen (für Monitoring/SIEM-Anbindung)
  • quarantine-only — nur Quarantäne-Aktionen (Release, Discard, Re-Train)
  • domain-admin — alle Operationen für eine spezifische Domain (für Mandanten-Self-Service)
  • full-admin — alle Operationen, kein Scope-Limit (für Operator-CLI-Tools)

Rate-Limit

Pro Key konfigurierbar (Default 100 Requests/Minute). Token-Bucket-Verfahren — Bursts bis 10× der Sustained-Rate erlaubt, danach 429 Too Many Requests mit Retry-After-Header. Das schützt vor:

  • Versehentlichen Endlos-Schleifen im integrierten System
  • Kompromittierten API-Keys die plötzlich gegen den Cluster hämmern
  • Performance-Regression auf Cluster-Nodes durch eine über-aktive Integration

OpenAPI-Spec

Versionierter Vertrag in openapi.yaml, ausgeliefert mit jedem Release. Erreichbar unter /api/v1/openapi.yaml. Mit jedem Release-Tag versioniert — Breaking-Changes nur in Major-Version-Übergängen, Deprecation-Notices 6 Monate vorher.

Importierbar in Postman, Insomnia, OpenAPI-Generator (für Client-Bibliotheken in Go, Python, JavaScript, Java etc.).

Webhooks

Für Real-Time-Integration. Operator konfiguriert URL + geheimes HMAC-Token + Event-Typen. Bei jedem Event POSTet MailGuard ein JSON-Payload mit signierter Header (HMAC-SHA256). Verfügbare Events:

  • quarantine.added — Mail in Quarantäne gelandet
  • quarantine.released — Mail freigegeben (Operator oder End-User)
  • quarantine.discarded — Mail verworfen
  • reputation.threshold_crossed — Sender-IP-Reputation hat eine Schwelle über/unterschritten
  • license.changed — Tier-Wechsel oder Lizenz-Refresh
  • cluster.node_joined / cluster.node_left — Cluster-Events
  • dkim.rotation_due — DKIM-Schlüssel-Rotation steht an (30 Tage Vorwarnung)
  • cert.expiring — TLS-Zertifikat läuft demnächst ab

Audit-Log via API

Endpoint GET /api/v1/audit/logs mit Filter-Parametern (Zeitraum, Akteur, Ressource). JSON-Format. Per Cursor-Pagination — kein Limit auf Output-Größe, keine Datenverlust beim Export. Ideal für SIEM-Anbindung — typischerweise pollt der SIEM-Forwarder alle 5 Minuten und persistiert Events lokal.

Response-Envelope

Einheitlich für alle Endpoints — kein Mix-Pattern wie bei vielen Cloud-APIs:

{
  "data":    { ... } | [...] | null,
  "error":   null | "string",
  "message": "human-readable status"
}

API-first ist nicht Aufpreis — ist Architektur.

REST-API ist im Standard-Plan inkludiert. Webhooks ebenfalls. Free-Tier hat Read-Only-Endpoints für lokales Monitoring.

Preise ansehen