Quarantäne-Endpoints¶

REST-API für Quarantäne-Management. Operationen sind cluster-weit aggregiert — keine Notwendigkeit, Endpoints pro Cluster-Node anzusprechen.

`GET /mail/quarantine`¶

Liste aller quarantänen Mails clusterweit.

curl -H 'X-API-Key: nmg_<...>' \
     'https://mailguard.example.com:3443/api/v1/mail/quarantine?limit=50'

Query-Parameter¶

Parameter	Bedeutung
`limit`	Max. Anzahl Einträge (Default 100, max 1000)
`offset`	Pagination-Offset
`domain`	Nur Mails an spezifische Empfänger-Domain
`sender`	Nur Mails von spezifischer Sender-Adresse oder -Domain
`since`	Nur Mails empfangen seit ISO-Zeitstempel
`min_score` / `max_score`	Score-Range-Filter
`reason`	Filter nach Detection-Reason (`spam`, `phishing`, `sandbox`, `rbl`)

Response¶

{
  "data": [
    {
      "node_id": "node-1",
      "queue_id": "4F2A8C0D",
      "sender": "noreply@phisher.tk",
      "recipients": ["alice@example.com"],
      "subject": "Konto gesperrt — sofort handeln",
      "score": 14.7,
      "symbols": ["DACH_PHISHING_SUBJECT", "FISHY_TLD", "RBL_HIT"],
      "reason": "phishing",
      "size_bytes": 12483,
      "arrived_at": "2026-05-01T07:42:13Z"
    }
  ],
  "error": null,
  "message": "OK"
}

Mail freigeben (Release)¶

curl -X POST -H 'X-API-Key: nmg_<...>' \
     'https://mailguard.example.com:3443/api/v1/mail/quarantine/{node_id}/{queue_id}/release'

Routet automatisch zum Owner-Node (der Node, auf dem die Mail physisch in der Hold-Queue liegt). Mail wird per postsuper -H aus der Hold-Queue entlassen und ausgeliefert.

Mail verwerfen (Discard)¶

curl -X POST -H 'X-API-Key: nmg_<...>' \
     'https://mailguard.example.com:3443/api/v1/mail/quarantine/{node_id}/{queue_id}/discard'

postsuper -d auf dem Owner-Node, Mail wird gelöscht.

Mail anzeigen / Body abrufen¶

curl -H 'X-API-Key: nmg_<...>' \
     'https://mailguard.example.com:3443/api/v1/mail/quarantine/{node_id}/{queue_id}/body'

Liefert die rohe RFC-822-Mail (eml-Format) als text/rfc822. Für forensische Analyse oder zum Archivieren geeignet.

Cluster-Aggregation¶

Bei einem Multi-Node-Cluster ruft der Endpoint die Hold-Queue jedes Nodes via mTLS auf und merged die Resultate. Bei sehr großem Volumen (10.000+ quarantänen Mails) kann die Aggregation 1-3 Sekunden dauern — Filter einschränken hilft.