Sophos Email Post-Delivery Quarantine via de API beheren

Post-Delivery Quarantine bevat berichten die eerst zijn bezorgd en daarna door Post-Delivery Protection uit het postvak zijn verwijderd. De API gebruikt daarom de aparte padfamilie /post-delivery-quarantine. De gelijknamige endpoints onder /quarantine horen bij de gewone quarantaine vóór bezorging en zijn niet uitwisselbaar.

De veilige volgorde is: gericht zoeken, treffer en ontvanger verifiëren, bericht of bijlagen inspecteren, alleen goedgekeurde ID’s wijzigen en daarna de status opnieuw opvragen. Aan de slag met de Email Management API licht de API-families toe. OAuth2, tenant en regionale routering voorbereiden levert de gebruikte toegangswaarden.

Vereisten en requestbasis vastleggen

Post-Delivery Protection moet voor het domein actief zijn, er moet een service principal zijn en diens machtiging voor Post-Delivery Quarantine moet zijn bevestigd. Neem alleen deze gevalideerde waarden over:

SOPHOS_ACCESS_TOKEN: actueel Bearer-token;
SOPHOS_TENANT_ID: UUID van de doeltenant;
SOPHOS_API_HOST: regionale host die voor precies deze tenant is gevonden.

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

Elke aanroep verstuurt de header Authorization met Bearer gevolgd door de huidige SOPHOS_ACCESS_TOKEN, de header X-Tenant-ID met de waarde SOPHOS_TENANT_ID en Accept: application/json; JSON-requests versturen ook Content-Type: application/json. Tenant, token en host moeten bij elkaar horen. Los 403 op via de API-machtiging en tenanttoewijzing, niet door andere tenants te proberen. De voorbeelden zijn gebaseerd op Email Management API v1.4.0; controleer vóór implementatie opnieuw het actuele contract.

Gericht naar post-deliveryberichten zoeken

POST /post-delivery-quarantine/messages/search vereist beginDate en endDate. Optioneel zijn page (vanaf 1), pageSize (standaard 50, maximaal 100), sort en filter. Gedocumenteerde filters zijn id, fromContains, toContains, subjectContains, attachmentNameContains, sizeInMBGreaterThan, sizeInMBLowerThan, productType, reason en hasAnyAttachment. productType accepteert mailflow, gateway of ems; reason accepteert malware, maliciousUrl of onDemand.

Begin met een kort UTC-venster en bekende kenmerken:

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"]
  }
}

Vervang tijd en adres door het goedgekeurde onderzoeksbereik. De response bevat items en pages. Begin bij pagina 1 en verhoog page telkens met precies één. Stop bij het bereiken van pages.total als dit veld aanwezig is; stop anders bij de eerste lege pagina of een pagina met minder items dan de gevraagde pageSize. Stel vooraf maximale aantallen pagina’s en looptijd in en markeer de zoekactie als onvolledig als de paginering ongeldig is, zich herhaalt, niet voortgaat of een grens wordt bereikt. Vergelijk vóór een wijziging minstens id, forRecipient, quarantinedAt, reason, onderwerp en tenant. id komt uit de MIME-header X-Sophos-Email-ID, niet uit MIME Message-ID of o365MessageId.

Inhoud en bijlagen inspecteren

GET /post-delivery-quarantine/messages/{id}/preview retourneert headers en, indien aanwezig, htmlBody en textBody.
GET /post-delivery-quarantine/messages/{id}/attachments?page=1&pageSize=50 retourneert bijlagenamen en sizeInBytes met pages. Standaard gelden pagina 1 en 50 items; de response ondersteunt maximaal 500 items per pagina.

Een voorbeeld kan schadelijke en vertrouwelijke inhoud bevatten. Render HTML niet actief, open geen links en log responses niet ongefilterd. De lijstaanroep downloadt nog geen bestand.

Stuur voor downloaden de gewenste bijlagenamen naar POST /post-delivery-quarantine/messages/{id}/attachments/download. Zonder attachments downloadt de taak alle bijlagen; geef daarom bij voorkeur een expliciete lijst:

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

De response bevat taak-id en status. Gebruik deze id als downloadId voor:

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

Poll met een begrensd interval zolang status processing is. Bij completed bevat de response namen en url; voor een beveiligde ZIP kan ook password aanwezig zijn. Onderzoek bij failed het veld error en start niet onbeperkt opnieuw. Open bestanden alleen geïsoleerd en zet URL of wachtwoord niet in logs of tickets.

Vrijgeven of verwijderen

Beide schrijfacties accepteren maximaal 50 elementen in items. Elk element vereist de post-delivery-id; forRecipients beperkt de actie tot specifieke ontvangers. Zonder forRecipients geldt ze volgens de gids voor alle ontvangers van het bericht.

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

POST /post-delivery-quarantine/messages/release zet berichten in de wachtrij voor vrijgave. HTTP 202 betekent geaccepteerd, niet bevestigd in het postvak.
POST /post-delivery-quarantine/messages/delete verwijdert berichten. De beoordeelde specificatie retourneert bij succes HTTP 200; behandel dit dus niet als downloadtaak.

Documenteer vóór vrijgave inhoud, ontvangersbereik en goedkeuring. Bewaar of exporteer vóór beide schrijfacties het bewijsmateriaal dat voor het onderzoek nodig is. Voor een geslaagde delete is geen API-bewerking voor ongedaan maken of herstellen gedocumenteerd; eis goedkeuring voor de verwijdering en escaleer elke onzekerheid vóór deze onomkeerbare stap. Een release bezorgt het bericht opnieuw, maar maakt de oorspronkelijke terughaalactie uit het postvak niet herhaalbaar. Herhaal niet blind na timeout of 5xx, want het servereffect kan al zijn opgetreden.

Resultaten en gedeeltelijke fouten valideren

Vrijgave en verwijdering retourneren aparte arrays items en errors. Werk de goedgekeurde request vóór verzending uit tot concrete paren (id, recipient) en stem daarna elk gevraagd paar precies één keer af over beide arrays: een geslaagde entry in items bevat alleen id en recipient, terwijl een mislukte entry in errors id, recipient en error bevat. Beschouw de response als ongeldig en handel fail-closed als een gevraagd paar ontbreekt, dubbel voorkomt, in beide arrays staat of een niet-gevraagd paar wordt geretourneerd. Log voor elk paar de uitkomst en de geretourneerde error, zonder inhoud of tokens. Probeer alleen mislukte paren opnieuw die na de statuscontrole nog geldig en opnieuw goedgekeurd zijn; probeer geslaagde of ambigue paren nooit opnieuw.

Zoek daarna opnieuw op dezelfde id en ontvanger. Na succesvolle verwijdering mag het item niet meer in de gekozen scope staan; deze validatie bevestigt het destructieve resultaat, niet een herstelmogelijkheid. Wacht na geaccepteerde vrijgave op de statuswijziging en bevestig in het doelpostvak dat het bericht voor de juiste ontvanger terug is. Die bezorgbevestiging bewijst niet dat de oorspronkelijke terughaalactie opnieuw kan worden uitgevoerd. Controleer als het item in de zoekresultaten blijft of het bericht in het postvak ontbreekt de ontvanger, PDP-status en fout voordat dat deel opnieuw wordt beoordeeld.

geen treffer: controleer UTC-venster, pagina, tenant, ID-type en PDP-status;
404 bij preview, bijlagen of taak: controleer regionale host, post-deliverypad en betreffende ID;
download failed: onderzoek error en vergelijk namen met de actuele lijst;
gemengde bulkresponse: stem alle gevraagde paren af en probeer alleen nog geldige, opnieuw goedgekeurde mislukte paren opnieuw; handel fail-closed bij ontbrekende, dubbele, tegenstrijdige of onverwachte resultaten;
alleen treffer in gewone quarantaine: ga verder met /quarantine, zonder het bericht naar post-delivery over te dragen.

Zo blijft automatisering tenantgebonden, statusbewust en herhaalbaar zonder gewone en post-deliveryquarantaine te verwarren.