Hoppa till innehållet
Avanet

Hantera Sophos Email-karantänen via API

Sophos Email

Email Quarantine API behandlar meddelanden som Sophos Email har flyttat till den vanliga e-postsäkerhetskarantänen före leverans. Ett säkert arbetsflöde är att söka snävt, utvärdera varje sida, registrera X-Sophos-Email-ID och mottagaren, granska innehållet, utföra en ändring med litet omfång och kontrollera resultatet för varje mottagare.

Artikeln använder enbart sökvägar under /email/v1/quarantine. Den snarlikt namngivna Post-Delivery Quarantine gäller meddelanden som redan har levererats och sedan återkallats och har en egen endpointfamilj. Blanda inte dess sökvägar, ID:n eller tillstånd med detta flöde.

Förbered förutsättningar och variabler

Börja med introduktionen till Sophos Email Management API. Den planerade guiden Autentisera Sophos Email API och dirigera anrop till en klientorganisation beskriver tjänstens huvudnamn, klientorganisationsmatchning och minimibehörigheter mer ingående. Följande värden ska redan ha fastställts på ett säkert sätt:

  • SOPHOS_ACCESS_TOKEN: en kortlivad OAuth2-bearertoken;
  • SOPHOS_TENANT_ID: målklientorganisationens UUID;
  • SOPHOS_API_HOST: klientorganisationens regionala API-värd;
  • en Email Quarantine-behörighet som tilldelats tjänstens huvudnamn.
EMAIL_API_HOST="${SOPHOS_API_HOST%/}/email/v1"

Token, hämtnings-URL:er, ZIP-lösenord, MIME-huvuden och meddelandetext är hemligheter eller personuppgifter. De får inte hamna i skalhistorik, processargument, CI-utdata eller ärenden. JSON-blocken nedan är avsiktligt dokumentationsexempel; produktionsklienter skriver nyttolaster till skyddade temporära filer eller skickar dem via standardindata.

Kontrakten har kontrollerats mot Email Management API v1.4.0. Kontrollera metod, sökväg, schema, behörighet och gränser på nytt i den aktuella specifikationen före implementation.

Sök snävt i karantänen och sidindela alla resultat

POST /quarantine/messages/search kräver beginDate och endDate som ISO 8601-tidpunkter. Filter är valfria. Exemplet begränsar ett inkommande skadeprogramsfall till en mottagare och begär 100 poster, det dokumenterade maximumet per söksida:

{
  "beginDate": "2026-09-14T00:00:00.000Z",
  "endDate": "2026-09-15T00:00:00.000Z",
  "pageSize": 100,
  "sort": ["quarantinedAt:DESC"],
  "filter": {
    "direction": "inbound",
    "toContains": "analyst@example.test",
    "reason": ["malware"]
  }
}

Filterkontraktet omfattar id, fromContains, toContains, subjectContains, attachmentNameContains, hasAnyAttachment, sizeInMBGreaterThan, sizeInMBLowerThan, direction (inbound eller outbound), productType (mailflow, gateway eller ems) och reason. De dokumenterade sorteringsfälten är from, forRecipient och quarantinedAt. Med fields kan ett partiellt svar begäras; en klient får inte tolka utelämnade fält som tomma värden.

Svaret innehåller items och pages. Kopiera pages.nextKey oförändrad som en sträng till pageFromKey i nästa POST-body för att hämta nästa sida. Avsluta först när nextKey saknas och skydda dessutom loopen med gränser för sidantal och körtid samt detektering av upprepade nycklar. pages.size beskriver bara den aktuella sidan. En full eller tom första sida bevisar därför varken fullständighet eller att fler träffar saknas.

Registrera minst id, forRecipient, reason, quarantinedAt, direction och den planerade åtgärden för varje träff. id är UUID:t från MIME-huvudet X-Sophos-Email-ID; mimeMessageId är det vanliga Message-ID-huvudet och ersätter det inte i en API-sökväg eller massbegäran. Samma meddelande kan ha mottagarspecifika resultat.

Granska meddelandet, URL:erna och bilagorna

Alla tre läsåtgärder använder URL-kodat id i sökvägen:

GET /quarantine/messages/{id}/preview
GET /quarantine/messages/{id}/urls?pageSize=50&page=1
GET /quarantine/messages/{id}/attachments?pageSize=50&page=1

Förhandsvisningen returnerar headers, htmlBody och textBody. Behandla HTML som fientligt innehåll: rendera det inte direkt i en webbläsare eller administrationsportal, hämta inga externa resurser och öppna inga inbäddade länkar. Föredra text och utvalda huvuden vid analys.

URL- och bilagelistor använder numrerade sidor från 1. Standardvärdet för pageSize är 50; svaret anger tillåtet maximum i pages.maxSize och kan enligt det kontrollerade schemat innehålla upp till 500 element. Fortsätt tills pages.current når den senast angivna sidan eller tills en tom sida följer. Använd inte sökningens nyckelmodell (nextKey) här.

En URL-post är ett fynd, inte ett säkerhetsomdöme. En bilagepost innehåller name, sizeInBytes, fileType och stripped. Åtgärder adresserar bilagor med deras dokumenterade namn, inte med ett påhittat bilage-UUID. Gissa inte om namn är dubbletter eller listan är oväntad; utred fallet manuellt.

Hämta, ta bort eller återanslut bilagor

En hämtning är asynkron och sker i två steg. Starta först ett jobb för ett meddelande. Om attachments utelämnas omfattar jobbet alla bilagor; en uttrycklig lista är säkrare i ett kontrollerat fall:

POST /quarantine/messages/{id}/attachments/download

{
  "attachments": ["sample.zip"]
}

Svaret innehåller minst jobbets id och status. Detta jobb-ID blir downloadId i statussökvägen och får inte förväxlas med meddelande-ID:t:

GET /quarantine/downloads/{downloadId}/status

Polla med begränsad backoff tills status är completed eller failed. Vid completed kan attachments, en signerad url och ett password för den skyddade ZIP-filen visas. URL:en är kortlivat åtkomstmaterial: hämta den omgående endast till en isolerad, godkänd analysmiljö, logga den aldrig och använd jobbstatusen eller ett nytt auktoriserat hämtningsjobb om den löper ut. Utvärdera error vid failed; klienten får inte starta en oändlig serie nya jobb.

Strip och reattach ändrar det mottagarspecifika bilagetillståndet:

POST /quarantine/messages/{id}/attachments/strip
POST /quarantine/messages/{id}/attachments/reattach

{
  "attachments": ["sample.zip"],
  "forRecipients": ["analyst@example.test"]
}

forRecipients begränsar ändringen. Utan begränsningen kan åtgärden påverka andra mottagare av meddelandet. Dela alltid upp svaret i lyckade items och misslyckade errors. Hämta därefter bilagelistan på nytt och kontrollera stripped för det avsedda namnet. Reattach frisläpper inte meddelandet och bevisar inte att bilagan är säker.

Frisläpp eller radera meddelanden kontrollerat

Release och delete accepterar högst 50 poster per begäran. Varje post kräver X-Sophos-Email-ID; forRecipients är valfritt men är den säkra avgränsningen för en mottagarspecifik åtgärd.

POST /quarantine/messages/release
POST /quarantine/messages/delete

En snävt avgränsad frisläppning ser ut så här:

{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "forRecipients": ["analyst@example.test"],
      "stripAttachments": ["sample.zip"]
    }
  ],
  "allowSender": false,
  "enforceSenderAuthentication": false,
  "submitMessageToLabs": false
}

Release returnerar HTTP 202: meddelandet har accepterats och köats för frisläppning, inte bevisligen levererats. allowSender och enforceSenderAuthentication förblir som standard false. Tillåt en avsändare först efter ett separat säkerhetsgodkännande; om allowSender aktiveras avsiktligt ska avsändarautentiseringen inte av misstag förbli avstängd. submitMessageToLabs gäller endast skräppost- och virusmeddelanden. stripAttachments verkar per frisläppningspost.

Begär borttagning separat och utan att implicit blockera avsändaren:

{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "forRecipients": ["analyst@example.test"]
    }
  ],
  "blockSender": false
}

Delete returnerar HTTP 200 vid framgång. blockSender är en ytterligare och bredare policyändring och förblir false utan ett godkänt blockeringsuppdrag. Upprepa inte release eller delete blint efter en timeout: servern kan redan ha accepterat den första begäran.

Båda massvaren kan samtidigt innehålla items och errors. HTTP-framgång betyder därför inte att varje ID/mottagarpar lyckades. Matcha varje begärt par exakt en gång mot båda arrayerna; saknade, dubbla eller motsägelsefulla resultat ska stoppa en automatisk framgångsrapport.

Verifiera resultatet

Utför följande kontroller för varje ändring:

  1. Logga request ID eller correlation ID, HTTP-status, tid, klientorganisation och en maskerad lista över ID/mottagarpar; spara inte innehåll eller hemligheter.
  2. Lista bilagorna på nytt efter strip/reattach och kontrollera stripped för varje namn.
  3. Utvärdera alla items och errors efter release, upprepa sedan samma karantänsökning och verifiera faktisk leverans med avsett driftbevis. Enbart 202 räcker inte.
  4. Utvärdera alla items och errors efter delete och upprepa samma sökning. Använd en saknad post som bevis endast tillsammans med det positiva massvaret, eftersom tidsintervall och filter också kan dölja träffar.
  5. Matcha downloadId, slutstatus och begärda filnamn vid hämtningar; ta bort URL och lösenord från minne och temporär lagring efteråt.

Åtgärda partiella fel, utgångna jobb och behörigheter

  • En del av massåtgärden misslyckas: Utvärdera errors efter id, recipient och error. Skicka inte lyckade par igen. Behandla i en ny begäran endast felpar som fortfarande finns och har godkänts på nytt.
  • 400 Bad Request: Kontrollera JSON-typer, obligatoriska fält, ISO-tidpunkter, UUID, enumvärden, sidindelningsmodell och respektive gräns på 50 eller 100. pageFromKey är en sträng, inte ett sidnummer.
  • 401 eller 403: Förnya token genom det normala OAuth2-flödet eller kontrollera tilldelningen till tjänstens huvudnamn, Email Quarantine-behörigheten och klientorganisationen. Byt inte till en annan klientorganisation eller värd.
  • 404 eller ogiltigt ID: Säkerställ att UUID:t kommer från X-Sophos-Email-ID, fortfarande finns i den vanliga karantänen och tillhör klientorganisationen. Använd inte mimeMessageId, downloadId eller ett Post-Delivery-ID.
  • Hämtningen förblir processing: Begränsa pollningsintervallet och den totala tiden, kontrollera jobb-ID och klientorganisation och eskalera med request/correlation ID. Starta inte ständigt nya parallella jobb.
  • Hämtningen är failed eller URL:en har löpt ut: Spara error, kontrollera status en gång till och starta en ny hämtning endast om uppdraget fortfarande gäller. Ändra eller återanvänd inte en signerad URL.
  • Bilagan saknas eller tillståndet avviker: Läs alla numrerade bilagesidor, jämför namnen exakt och kontrollera errors per mottagare. Stoppa vid namnkollisioner eller om meddelandet redan har frisläppts.
  • Frisläppningen försvinner från listan men kommer inte fram: Den köades bara. Kontrollera mottagaren, upprepa filtreringen och granska efterföljande leveransbevis; frisläpp inte automatiskt igen.

En eskalering ska innehålla API-version, regional värd utan autentiseringsuppgifter, klientorganisations-ID, UTC-tidsintervall, metod och sökväg, HTTP-status, request/correlation ID samt maskerade objekt-ID:n och felkoder. Exkludera token, signerade URL:er, ZIP-lösenord, meddelandetext och bilagor.