Hantera Sophos Email Post-Delivery Quarantine via API

Post-Delivery Quarantine innehåller meddelanden som först levererades och sedan togs bort från postlådan av Post-Delivery Protection. API:t använder därför den separata sökvägsfamiljen /post-delivery-quarantine. Liknande endpoints under /quarantine gäller vanlig karantän före leverans och kan inte användas omväxlande.

Den säkra ordningen är att söka snävt, verifiera träff och mottagare, granska meddelande eller bilagor, ändra endast godkända ID:n och sedan fråga efter status igen. Kom igång med Email Management API förklarar API-familjerna. Förbered OAuth2, klientorganisation och regional routning ger åtkomstvärdena som används här.

Fastställ krav och requestbas

Post-Delivery Protection måste vara aktiverat för domänen, en service principal måste vara konfigurerad och dess behörighet för Post-Delivery Quarantine bekräftad. Använd endast dessa validerade värden:

SOPHOS_ACCESS_TOKEN: aktuell Bearer-token;
SOPHOS_TENANT_ID: målklientorganisationens UUID;
SOPHOS_API_HOST: regional värd som identifierats för exakt denna klientorganisation.

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

Varje anrop skickar headern Authorization med Bearer följt av aktuell SOPHOS_ACCESS_TOKEN, headern X-Tenant-ID med värdet SOPHOS_TENANT_ID och Accept: application/json; JSON-anrop skickar även Content-Type: application/json. Klientorganisation, token och värd måste höra ihop. Lös 403 genom att kontrollera API-behörighet och klienttilldelning, inte genom att prova andra klienter. Exemplen bygger på granskad Email Management API v1.4.0; kontrollera det aktuella kontraktet före implementation.

Sök snävt efter post-delivery-meddelanden

POST /post-delivery-quarantine/messages/search kräver beginDate och endDate. Valfria fält är page (från 1), pageSize (standard 50, högst 100), sort och filter. Dokumenterade filter är id, fromContains, toContains, subjectContains, attachmentNameContains, sizeInMBGreaterThan, sizeInMBLowerThan, productType, reason och hasAnyAttachment. productType godtar mailflow, gateway eller ems; reason godtar malware, maliciousUrl eller onDemand.

Börja med ett kort UTC-intervall och kända egenskaper:

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

Ersätt tid och adress med godkänt undersökningsomfång. Svaret innehåller items och pages. Börja på sida 1 och öka page med exakt ett. Om pages.total finns, stoppa när det totala antalet har nåtts; stoppa annars vid den första tomma sidan eller en sida med färre objekt än begärd pageSize. Ange maximalt sidantal och maximal körtid före start och markera sökningen som ofullständig om sidinformationen är felaktig, upprepas, inte går framåt eller når någon av gränserna. Jämför före ändring minst id, forRecipient, quarantinedAt, reason, ämne och klientorganisation. id kommer från MIME-headern X-Sophos-Email-ID, inte MIME Message-ID eller o365MessageId.

Granska innehåll och bilagor

GET /post-delivery-quarantine/messages/{id}/preview returnerar headers och, när de finns, htmlBody och textBody.
GET /post-delivery-quarantine/messages/{id}/attachments?page=1&pageSize=50 returnerar bilagenamn och sizeInBytes med pages. Standard är sida 1 och 50 objekt; svaret kan stödja upp till 500 objekt per sida.

Förhandsvisningen kan innehålla skadligt och konfidentiellt innehåll. Rendera inte HTML aktivt, öppna inte länkar och logga inte svar ofiltrerat. Listan hämtar ännu ingen fil.

Skicka önskade bilagenamn till POST /post-delivery-quarantine/messages/{id}/attachments/download. Utan attachments hämtar jobbet alla bilagor; ange därför helst en explicit lista:

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

Svaret innehåller jobbets id och status. Använd detta id som downloadId för:

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

När status är processing, polla med begränsat intervall. Vid completed innehåller svaret namn och url; för en skyddad ZIP kan även password finnas. Vid failed, granska error i stället för att starta om utan gräns. Öppna filer endast i isolerad analysmiljö och lägg inte URL eller lösenord i loggar eller ärenden.

Frisläpp eller radera

Båda skrivoperationerna godtar högst 50 element i items. Varje element kräver post-delivery-id; forRecipients begränsar åtgärden till vissa mottagare. Utan forRecipients gäller åtgärden enligt guiden alla meddelandets mottagare.

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

POST /post-delivery-quarantine/messages/release köar meddelanden för frisläppning. HTTP 202 betyder accepterad, inte bekräftad i postlådan.
POST /post-delivery-quarantine/messages/delete raderar meddelanden. Den granskade specifikationen returnerar HTTP 200 vid framgång; behandla därför inte radering som ett hämtningsjobb.

Dokumentera innehåll, mottagaromfång och godkännande före frisläppning. Bevara eller exportera bevismaterialet som utredningen kräver före båda skrivåtgärderna. För en lyckad delete finns ingen dokumenterad API-åtgärd för att ångra eller återställa; kräv godkännande för raderingen och eskalera all osäkerhet före detta oåterkalleliga steg. Ett release levererar meddelandet på nytt, men gör inte det ursprungliga återkallandet från postlådan repeterbart. Upprepa inte blint efter timeout eller 5xx, eftersom servereffekten redan kan ha inträffat.

Validera resultat och partiella fel

Frisläppning och radering returnerar separata arrayer items och errors. Expandera den godkända begäran till konkreta par (id, recipient) före sändning och stäm sedan av varje begärt par exakt en gång över båda arrayerna: en lyckad post i items innehåller endast id och recipient, medan en misslyckad post i errors innehåller id, recipient och error. Betrakta svaret som ogiltigt och använd fail-closed om ett begärt par saknas, är duplicerat, finns i båda arrayerna eller om ett ej begärt par returneras. Logga utfallet och returnerat error för varje par, utan innehåll eller token. Försök endast igen med misslyckade par som fortfarande är giltiga efter statuskontrollen och har godkänts på nytt; försök aldrig igen med lyckade eller tvetydiga par.

Sök sedan igen efter samma id och mottagare. Efter lyckad radering får objektet inte längre finnas i valt omfång; denna validering bekräftar det destruktiva resultatet, inte en återställningsväg. Efter accepterad frisläppning väntar du på statusändringen och bekräftar i målpostlådan att meddelandet återkommit för rätt mottagare. Leveransbekräftelsen bevisar inte att det ursprungliga återkallandet kan köras igen. Om objektet ligger kvar i sökningen eller meddelandet saknas i postlådan kontrollerar du mottagare, PDP-status och returnerat fel innan delen utvärderas igen.

ingen träff: kontrollera UTC-intervall, sida, klientorganisation, ID-typ och PDP-status;
404 för förhandsvisning, bilagor eller jobb: kontrollera regional värd, post-delivery-sökväg och rätt ID;
hämtning failed: granska error och jämför namn med aktuell lista;
blandat bulksvar: stäm av alla begärda par och försök endast igen med fortfarande giltiga, återgodkända misslyckade par; använd fail-closed för saknade, duplicerade, motstridiga eller oväntade resultat;
träff endast i vanlig karantän: fortsätt med /quarantine utan att överföra meddelandet till post-delivery-familjen.

Automatiseringen förblir därmed klientorganisationsbunden, statusmedveten och repeterbar utan att blanda ihop karantäntyperna.