Gestire la quarantena post-consegna di Sophos Email tramite API

La quarantena post-consegna contiene messaggi inizialmente consegnati e poi rimossi dalla casella di posta da Post-Delivery Protection. La relativa API usa quindi la famiglia di percorsi separata /post-delivery-quarantine. Gli endpoint dal nome simile sotto /quarantine riguardano la quarantena ordinaria prima della consegna e non sono intercambiabili.

La sequenza sicura consiste nel limitare la ricerca, verificare risultato e destinatario, esaminare messaggio o allegati, modificare solo gli ID approvati e interrogare nuovamente lo stato. Introduzione alla Email Management API illustra le famiglie di API. Preparare OAuth2, tenant e routing regionale fornisce i valori di accesso usati qui.

Definire prerequisiti e base delle richieste

Prima della prima chiamata, Post-Delivery Protection deve essere abilitata per il dominio interessato, deve essere configurato un service principal e va confermata la relativa autorizzazione per Post-Delivery Quarantine. Dal flusso di autenticazione si riprendono solo questi valori convalidati:

SOPHOS_ACCESS_TOKEN: token Bearer corrente;
SOPHOS_TENANT_ID: UUID del tenant di destinazione;
SOPHOS_API_HOST: host regionale individuato per quel tenant specifico.

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

Ogni chiamata invia l’header Authorization con Bearer seguito dal SOPHOS_ACCESS_TOKEN corrente, l’header X-Tenant-ID con il valore SOPHOS_TENANT_ID e Accept: application/json; le richieste JSON inviano anche Content-Type: application/json. Tenant, token e host regionale devono corrispondere. Un 403 si risolve controllando autorizzazione API e assegnazione del tenant, non provando altri tenant. Gli esempi si basano sulla Email Management API v1.4.0 esaminata; verificare nuovamente il contratto corrente prima dell’implementazione.

Cercare con precisione i messaggi post-consegna

POST /post-delivery-quarantine/messages/search richiede i timestamp beginDate e endDate. Sono facoltativi page (a partire da 1), pageSize (valore predefinito 50, massimo 100), sort e filter. I filtri documentati sono id, fromContains, toContains, subjectContains, attachmentNameContains, sizeInMBGreaterThan, sizeInMBLowerThan, productType, reason e hasAnyAttachment. productType accetta mailflow, gateway o ems; reason accetta malware, maliciousUrl o onDemand.

Avviare un’indagine controllata con un breve intervallo UTC e attributi noti:

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

Sostituire orario e indirizzo di esempio con l’ambito d’indagine approvato. La risposta contiene items e pages. Iniziare dalla pagina 1 e incrementare page esattamente di uno. Se pages.total è presente, fermarsi al raggiungimento di quel totale; altrimenti fermarsi alla prima pagina vuota o con meno elementi del pageSize richiesto. Stabilire prima dell’avvio limiti massimi di pagine e durata e dichiarare la ricerca incompleta se la paginazione è errata, si ripete, non avanza o raggiunge uno dei limiti. Prima di una modifica confrontare almeno id, forRecipient, quarantinedAt, reason, oggetto e tenant previsto. id è il valore dell’header MIME X-Sophos-Email-ID, non il Message-ID MIME né o365MessageId.

Esaminare contenuto e allegati

Per ogni id trovato sono disponibili due operazioni di lettura:

GET /post-delivery-quarantine/messages/{id}/preview restituisce headers e, se presenti, htmlBody e textBody.
GET /post-delivery-quarantine/messages/{id}/attachments?page=1&pageSize=50 restituisce nomi degli allegati e sizeInBytes con pages. I valori predefiniti sono pagina 1 e 50 elementi; la risposta può contenere fino a 500 elementi per pagina.

L’anteprima può contenere dati dannosi e riservati. Non eseguire il rendering attivo dell’HTML, non aprire link e non registrare risposte senza filtrarle. La chiamata di elenco non scarica ancora alcun file.

Per il download, inviare i nomi degli allegati desiderati a POST /post-delivery-quarantine/messages/{id}/attachments/download. Se si omette attachments, il job scarica tutti gli allegati; è quindi preferibile fornire un elenco esplicito:

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

La risposta contiene id e status del job. Questo id diventa il downloadId per:

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

Finché status è processing, eseguire il polling con un intervallo limitato. Con completed, la risposta contiene nomi e url; per uno ZIP protetto può essere presente anche password. Con failed, esaminare error invece di riavviare all’infinito la stessa richiesta. Aprire i file solo in un ambiente di analisi isolato e non inserire URL o password in log o ticket.

Rilasciare o eliminare

Entrambe le operazioni di scrittura accettano al massimo 50 elementi in items. Ogni elemento richiede l’id post-consegna; forRecipients limita l’azione a destinatari specifici. Se forRecipients manca, la guida applica l’azione a tutti i destinatari del messaggio.

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

POST /post-delivery-quarantine/messages/release accoda uno o più messaggi per il rilascio. HTTP 202 significa accettato, non confermato nella casella.
POST /post-delivery-quarantine/messages/delete elimina uno o più messaggi da Post-Delivery Quarantine. La specifica esaminata restituisce HTTP 200 in caso di successo; l’eliminazione non viene quindi trattata come job di download.

Prima del rilascio documentare contenuto, ambito dei destinatari e approvazione. Conservare o esportare le prove necessarie all’indagine prima di entrambe le operazioni di scrittura. Per un delete riuscito non è documentata alcuna operazione API di annullamento o ripristino; richiedere l’approvazione dell’eliminazione e segnalare ogni dubbio prima di questo passaggio irreversibile. Un release riconsegna il messaggio, ma non rende ripetibile il richiamo originale dalla casella di posta. Non riprovare automaticamente dopo un timeout o 5xx: l’effetto lato server potrebbe essere già avvenuto.

Verificare risultati ed errori parziali

Rilascio ed eliminazione restituiscono array distinti items ed errors. Prima dell’invio, espandere la richiesta approvata in coppie concrete (id, recipient), quindi riconciliare ogni coppia richiesta esattamente una volta tra i due array: una voce riuscita di items contiene solo id e recipient, mentre una voce non riuscita di errors contiene id, recipient ed error. Considerare la risposta non valida e interrompere in modalità fail-closed se una coppia richiesta manca, è duplicata, compare in entrambi gli array o viene restituita una coppia non richiesta. Registrare l’esito e l’error restituito per ogni coppia, senza contenuto o token. Riprovare solo le coppie non riuscite ancora valide dopo il controllo dello stato e nuovamente approvate; non riprovare mai coppie riuscite o ambigue.

Cercare poi nuovamente lo stesso id e il destinatario interessato. Dopo un’eliminazione riuscita l’elemento non deve più apparire nell’ambito post-consegna scelto; questa verifica conferma l’esito distruttivo, non un percorso di ripristino. Dopo un rilascio accettato, attendere il cambio di stato e confermare anche nella casella di destinazione che il messaggio sia nuovamente presente per il destinatario previsto. Tale conferma di consegna non dimostra che il richiamo originale possa essere eseguito di nuovo. Se l’elemento resta nella ricerca o il messaggio manca dalla casella, controllare destinatario, stato PDP ed errore restituito prima di rivalutare quella parte.

Queste distinzioni aiutano nella risoluzione dei problemi:

nessun risultato: controllare intervallo UTC, pagina, tenant, tipo di ID e stato PDP;
404 per anteprima, allegati o job: controllare host regionale, percorso post-delivery e ID pertinente;
download failed: esaminare error e confrontare i nomi con l’elenco corrente;
risposta bulk mista: riconciliare tutte le coppie richieste e riprovare solo gli errori ancora validi e nuovamente approvati; interrompere in modalità fail-closed per risultati mancanti, duplicati, contraddittori o inattesi;
risultato solo nella quarantena ordinaria: continuare con /quarantine, senza trasferire il messaggio nella famiglia post-delivery.

L’automazione resta così vincolata al tenant, consapevole dello stato e ripetibile, senza confondere quarantena ordinaria e post-consegna.