Sophos Email Post-Delivery-Quarantäne per API verwalten

Die Post-Delivery-Quarantäne enthält Nachrichten, die zuerst zugestellt und danach durch Post-Delivery Protection aus dem Postfach zurückgezogen wurden. Ihre API verwendet deshalb die eigene Pfadfamilie /post-delivery-quarantine; die ähnlich benannten Endpunkte unter /quarantine betreffen die gewöhnliche Quarantäne vor der Zustellung und sind nicht austauschbar.

Der sichere Ablauf lautet: eng suchen, Treffer und Empfänger prüfen, Nachricht beziehungsweise Anhänge untersuchen, genau die freigegebenen IDs ändern und den Zustand danach erneut abfragen. Der Einstieg in die Email Management API ordnet die API-Familien ein. OAuth2, Tenant und Regionalhost vorbereiten liefert die hier verwendeten Zugangswerte.

Voraussetzungen und Request-Basis

Vor dem ersten Aufruf müssen Post-Delivery Protection für die betroffene Domain aktiv, ein Service Principal eingerichtet und dessen Berechtigung für die Post-Delivery-Quarantäne bestätigt sein. Aus dem Authentifizierungsablauf werden ausschliesslich diese geprüften Werte übernommen:

SOPHOS_ACCESS_TOKEN: aktueller Bearer-Token;
SOPHOS_TENANT_ID: UUID des Ziel-Tenants;
SOPHOS_API_HOST: für genau diesen Tenant ermittelter Regionalhost.

EMAIL_API_HOST="${SOPHOS_API_HOST%/}/email/v1"

Jeder Aufruf sendet den Header Authorization mit Bearer gefolgt vom aktuellen SOPHOS_ACCESS_TOKEN, den Header X-Tenant-ID mit dem Wert SOPHOS_TENANT_ID und Accept: application/json; bei JSON-Requests zusätzlich Content-Type: application/json. Tenant-ID, Token und Regionalhost müssen zusammengehören. Ein 403 wird durch Prüfung der API-Berechtigung und Tenantzuordnung behoben, nicht durch Probieren anderer Tenants. Die Beispiele beruhen auf der geprüften Email Management API v1.4.0; vor der Implementierung ist der aktuelle Vertrag erneut zu prüfen.

Post-Delivery-Nachrichten eng suchen

POST /post-delivery-quarantine/messages/search verlangt beginDate und endDate als Zeitstempel. Optional sind page (ab 1), pageSize (Standard 50, maximal 100), sort sowie filter. Belegte Filter sind id, fromContains, toContains, subjectContains, attachmentNameContains, sizeInMBGreaterThan, sizeInMBLowerThan, productType, reason und hasAnyAttachment. productType akzeptiert mailflow, gateway oder ems; reason akzeptiert malware, maliciousUrl oder onDemand.

Für eine kontrollierte Untersuchung beginnt man mit einem kurzen UTC-Zeitfenster und bekannten Merkmalen:

POST /email/v1/post-delivery-quarantine/messages/search

{
  "beginDate": "2026-09-15T08:00:00.000Z",
  "endDate": "2026-09-15T09:00:00.000Z",
  "page": 1,
  "pageSize": 50,
  "sort": ["quarantinedAt:DESC"],
  "filter": {
    "toContains": "user@example.com",
    "reason": ["onDemand"]
  }
}

Die Beispielzeit und Adresse werden durch den eigenen freigegebenen Untersuchungsumfang ersetzt. Die Antwort enthält items und pages. Bei Seite 1 beginnen und page jeweils genau um eins erhöhen. Ist pages.total vorhanden, nach Erreichen dieser Gesamtzahl stoppen; andernfalls bei der ersten leeren Seite oder einer Seite mit weniger Elementen als dem angeforderten pageSize. Vor dem Start Höchstwerte für Seitenzahl und Laufzeit festlegen und die Suche als unvollständig abbrechen, wenn die Seitendaten fehlerhaft sind, sich wiederholen oder nicht fortschreiten oder ein Grenzwert erreicht wird. Vor einer Änderung mindestens id, forRecipient, quarantinedAt, reason, Betreff und erwarteten Tenant abgleichen. Die id ist der Wert aus dem MIME-Header X-Sophos-Email-ID, nicht die MIME-Message-ID und nicht o365MessageId.

Inhalt und Anhänge prüfen

Für eine einzelne gefundene id stehen zwei lesende Operationen bereit:

GET /post-delivery-quarantine/messages/{id}/preview liefert headers sowie, wenn vorhanden, htmlBody und textBody.
GET /post-delivery-quarantine/messages/{id}/attachments?page=1&pageSize=50 liefert Anhangsnamen und sizeInBytes mit pages. Die Standardwerte sind Seite 1 und 50 Einträge; die Antwort kann bis zu 500 Einträge pro Seite unterstützen.

Eine Vorschau ist potenziell schädlicher, vertraulicher Nachrichteninhalt. HTML nicht aktiv rendern, URLs nicht öffnen und Antwortdaten nicht ungefiltert protokollieren. Der Listenaufruf lädt noch keine Datei herunter.

Für einen Download sendet man die gewünschten Anhangsnamen an POST /post-delivery-quarantine/messages/{id}/attachments/download. Ohne attachments lädt der Auftrag alle Anhänge der Nachricht; deshalb die Liste vorzugsweise ausdrücklich setzen:

{
  "attachments": ["suspect-document.zip"]
}

Die Antwort enthält eine Job-id und status. Diese id ist der downloadId für:

GET /email/v1/post-delivery-quarantine/downloads/{downloadId}/status

Solange status den Wert processing hat, wird mit begrenztem Intervall weiter abgefragt. Bei completed enthält die Antwort die Anhangsnamen und url; für ein passwortgeschütztes ZIP kann zusätzlich password vorhanden sein. Bei failed wird error ausgewertet und nicht dieselbe Anfrage endlos neu gestartet. Heruntergeladene Dateien nur in einer isolierten Analyseumgebung öffnen und URL oder Passwort nicht in Logs oder Tickets übernehmen.

Freigeben oder löschen

Beide Schreiboperationen akzeptieren höchstens 50 Elemente in items. Jedes Element benötigt die Post-Delivery-id; forRecipients begrenzt die Aktion auf bestimmte Empfänger. Fehlt forRecipients, gilt die Aktion laut API-Leitfaden für alle Empfänger dieser Nachricht.

{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "forRecipients": ["user@example.com"]
    }
  ]
}

POST /post-delivery-quarantine/messages/release stellt eine oder mehrere Nachrichten zur Freigabe in die Warteschlange. HTTP 202 bedeutet angenommen, nicht bereits im Postfach bestätigt.
POST /post-delivery-quarantine/messages/delete löscht eine oder mehrere Nachrichten aus der Post-Delivery-Quarantäne. Die geprüfte Spezifikation liefert bei Erfolg HTTP 200; diese Löschung wird daher nicht als Download-Job behandelt.

Vor einer Freigabe müssen Inhalt, Empfängerumfang und Genehmigung dokumentiert sein. Vor beiden Schreiboperationen sind die für die Untersuchung benötigten Belege zu sichern oder zu exportieren. Für ein erfolgreiches delete ist keine API-Operation zum Rückgängigmachen oder Wiederherstellen dokumentiert; vor diesem unumkehrbaren Schritt ist die Löschgenehmigung einzuholen und jede Unsicherheit zu eskalieren. Ein release stellt die Nachricht erneut zu, macht den ursprünglichen Rückruf aus dem Postfach aber nicht wiederholbar. Bei Timeout oder 5xx nicht blind wiederholen: Die serverseitige Wirkung kann bereits eingetreten sein.

Ergebnis und Teilfehler prüfen

Freigabe und Löschung liefern getrennte Arrays items und errors. Die freigegebene Anfrage wird vor dem Senden in konkrete Paare (id, recipient) aufgelöst; danach muss jedes angeforderte Paar genau einmal über beide Arrays hinweg abgeglichen werden: Ein erfolgreicher Eintrag in items enthält nur id und recipient, ein fehlgeschlagener Eintrag in errors enthält id, recipient und error. Die Antwort ist ungültig und wird geschlossen abgebrochen, wenn ein angefordertes Paar fehlt, doppelt vorkommt, in beiden Arrays steht oder ein nicht angefordertes Paar zurückkommt. Für jedes Paar werden Ergebnis und zurückgegebenes error ohne Nachrichteninhalt oder Token protokolliert. Nur fehlgeschlagene Paare erneut versuchen, die nach der Zustandsprüfung noch gültig und erneut freigegeben sind; erfolgreiche oder mehrdeutige Paare nie wiederholen.

Danach dieselbe id und den betroffenen Empfänger erneut über die Post-Delivery-Suche prüfen. Nach erfolgreicher Löschung darf der Eintrag nicht mehr im gewählten Post-Delivery-Scope erscheinen; diese Prüfung bestätigt das destruktive Ergebnis, nicht einen Wiederherstellungsweg. Nach einer angenommenen Freigabe wartet man auf die Zustandsänderung und bestätigt zusätzlich im Zielpostfach, dass die Nachricht für den vorgesehenen Empfänger wieder vorhanden ist. Diese Zustellbestätigung belegt nicht, dass sich der ursprüngliche Rückruf erneut ausführen lässt. Bleibt der Eintrag in der Suche oder fehlt die Nachricht im Postfach, werden Empfänger, PDP-Zustand und zurückgegebener Fehler geprüft, bevor genau dieser Teil erneut bewertet wird.

Typische Abgrenzungen helfen bei der Fehlersuche:

kein Treffer: UTC-Zeitfenster, Seite, Tenant, id-Typ und PDP-Status kontrollieren;
404 bei Vorschau, Anhängen oder Jobstatus: Regionalhost, Post-Delivery-Pfad und jeweilige id prüfen;
failed beim Download: error auswerten und Anhangsnamen gegen die aktuelle Liste abgleichen;
gemischte Bulk-Antwort: alle angeforderten Paare abgleichen und nur noch gültige, erneut freigegebene Fehlerpaare wiederholen; bei fehlenden, doppelten, widersprüchlichen oder unerwarteten Ergebnissen geschlossen abbrechen;
Treffer nur in gewöhnlicher Quarantäne: mit /quarantine weiterarbeiten, nicht die Nachricht in die Post-Delivery-Familie übertragen.

Damit bleibt jede Automation tenantbezogen, zustandsbewusst und wiederholbar, ohne die Grenze zwischen gewöhnlicher und nachträglicher Quarantäne zu verwischen.