Gérer la quarantaine post-livraison de Sophos Email par API

La quarantaine post-livraison contient les messages d’abord livrés, puis retirés de la boîte aux lettres par Post-Delivery Protection. Son API utilise donc la famille de chemins distincte /post-delivery-quarantine. Les endpoints similaires sous /quarantine concernent la quarantaine ordinaire avant livraison et ne sont pas interchangeables.

La séquence sûre consiste à effectuer une recherche ciblée, vérifier le résultat et le destinataire, inspecter le message ou ses pièces jointes, ne modifier que les ID approuvés, puis interroger à nouveau l’état. Découvrir Email Management API présente les familles d’API. Préparer OAuth2, le tenant et le routage régional fournit les valeurs d’accès utilisées ici.

Établir les prérequis et la base des requêtes

Avant le premier appel, Post-Delivery Protection doit être activée pour le domaine concerné, un service principal doit être configuré et son autorisation Post-Delivery Quarantine confirmée. Seules les valeurs validées suivantes sont reprises du flux d’authentification :

SOPHOS_ACCESS_TOKEN : jeton Bearer actuel ;
SOPHOS_TENANT_ID : UUID du tenant cible ;
SOPHOS_API_HOST : hôte régional découvert pour ce tenant précis.

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

Chaque appel envoie l’en-tête Authorization avec Bearer suivi du SOPHOS_ACCESS_TOKEN actuel, l’en-tête X-Tenant-ID avec la valeur SOPHOS_TENANT_ID et Accept: application/json ; les requêtes JSON envoient aussi Content-Type: application/json. Le tenant, le jeton et l’hôte régional doivent correspondre. Un 403 se résout en contrôlant l’autorisation API et l’affectation du tenant, pas en essayant d’autres tenants. Les exemples reposent sur Email Management API v1.4.0 ; vérifiez à nouveau le contrat actuel avant l’implémentation.

Rechercher précisément les messages post-livraison

POST /post-delivery-quarantine/messages/search exige les horodatages beginDate et endDate. page (à partir de 1), pageSize (50 par défaut, 100 au maximum), sort et filter sont facultatifs. Les filtres documentés sont id, fromContains, toContains, subjectContains, attachmentNameContains, sizeInMBGreaterThan, sizeInMBLowerThan, productType, reason et hasAnyAttachment. productType accepte mailflow, gateway ou ems ; reason accepte malware, maliciousUrl ou onDemand.

Commencez une investigation contrôlée avec une courte plage UTC et des attributs connus :

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

Remplacez l’heure et l’adresse d’exemple par le périmètre d’investigation approuvé. La réponse contient items et pages. Commencez à la page 1 et incrémentez page exactement de un. Si pages.total est présent, arrêtez-vous lorsque ce total est atteint ; sinon, arrêtez-vous à la première page vide ou contenant moins d’éléments que le pageSize demandé. Fixez avant le départ des limites maximales de pages et de durée, puis considérez la recherche incomplète si la pagination est incorrecte, se répète, n’avance pas ou atteint l’une de ces limites. Avant toute mutation, comparez au minimum id, forRecipient, quarantinedAt, reason, l’objet et le tenant attendu. id est la valeur de l’en-tête MIME X-Sophos-Email-ID, et non le Message-ID MIME ni o365MessageId.

Inspecter le contenu et les pièces jointes

Deux opérations de lecture sont disponibles pour un id trouvé :

GET /post-delivery-quarantine/messages/{id}/preview renvoie headers et, s’ils existent, htmlBody et textBody.
GET /post-delivery-quarantine/messages/{id}/attachments?page=1&pageSize=50 renvoie les noms des pièces jointes et sizeInBytes avec pages. Les valeurs par défaut sont la page 1 et 50 éléments ; la réponse peut contenir jusqu’à 500 éléments par page.

Un aperçu peut contenir des données malveillantes et confidentielles. Ne rendez pas le HTML actif, n’ouvrez aucun lien et ne journalisez pas les réponses sans filtrage. L’appel de liste ne télécharge encore aucun fichier.

Pour télécharger, envoyez les noms des pièces jointes voulues à POST /post-delivery-quarantine/messages/{id}/attachments/download. Sans attachments, la tâche télécharge toutes les pièces jointes ; fournissez donc de préférence une liste explicite :

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

La réponse contient l’id d’une tâche et status. Cet id devient le downloadId pour :

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

Tant que status vaut processing, interrogez à intervalle borné. Avec completed, la réponse contient les noms et url ; password peut également être présent pour un ZIP protégé. Avec failed, analysez error plutôt que de relancer indéfiniment la même demande. N’ouvrez les fichiers que dans un environnement d’analyse isolé et ne placez ni l’URL ni le mot de passe dans des journaux ou tickets.

Libérer ou supprimer

Les deux opérations d’écriture acceptent au maximum 50 éléments dans items. Chaque élément requiert l’id post-livraison ; forRecipients limite l’action à certains destinataires. Sans forRecipients, le guide applique l’action à tous les destinataires du message.

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

POST /post-delivery-quarantine/messages/release place un ou plusieurs messages dans la file de libération. HTTP 202 signifie accepté, pas confirmé dans la boîte aux lettres.
POST /post-delivery-quarantine/messages/delete supprime un ou plusieurs messages de Post-Delivery Quarantine. La spécification examinée renvoie HTTP 200 en cas de succès ; cette suppression n’est donc pas traitée comme une tâche de téléchargement.

Avant une libération, documentez le contenu, le périmètre des destinataires et l’approbation. Conservez ou exportez les preuves nécessaires à l’enquête avant l’une ou l’autre opération d’écriture. Aucun mécanisme d’API permettant d’annuler ou de restaurer un delete réussi n’est documenté ; exigez l’approbation de la suppression et faites remonter toute incertitude avant cette étape irréversible. Un release remet le message en distribution, mais ne permet pas de répéter le retrait initial de la boîte aux lettres. Ne réessayez pas aveuglément après un timeout ou une erreur 5xx : l’effet côté serveur peut déjà avoir eu lieu.

Valider les résultats et les échecs partiels

La libération et la suppression renvoient des tableaux items et errors séparés. Avant l’envoi, développez la requête approuvée en paires concrètes (id, recipient), puis rapprochez chaque paire demandée exactement une fois dans l’ensemble des deux tableaux : une entrée réussie de items contient uniquement id et recipient, tandis qu’une entrée échouée de errors contient id, recipient et error. Considérez la réponse comme invalide et échouez en mode fermé si une paire demandée manque, est dupliquée, figure dans les deux tableaux ou si une paire non demandée est renvoyée. Journalisez le résultat et l’error renvoyé pour chaque paire, sans contenu ni jeton. Ne réessayez que les paires en échec qui restent valides après le contrôle d’état et sont de nouveau approuvées ; ne réessayez jamais les paires réussies ou ambiguës.

Recherchez ensuite à nouveau le même id et le destinataire concerné. Après une suppression réussie, l’élément ne doit plus apparaître dans le périmètre post-livraison choisi ; cette validation confirme le résultat destructif, pas une voie de récupération. Après une libération acceptée, attendez le changement d’état et confirmez aussi dans la boîte cible que le message est revenu pour le destinataire prévu. Cette confirmation de livraison ne prouve pas que le retrait initial peut être exécuté de nouveau. Si l’élément reste dans la recherche ou si le message manque dans la boîte, contrôlez le destinataire, l’état PDP et l’erreur renvoyée avant de réévaluer cette partie.

Ces distinctions facilitent le dépannage :

aucun résultat : vérifiez la plage UTC, la page, le tenant, le type d’ID et l’état PDP ;
404 pour l’aperçu, les pièces jointes ou la tâche : vérifiez l’hôte régional, le chemin post-livraison et l’ID concerné ;
téléchargement failed : analysez error et comparez les noms avec la liste actuelle ;
réponse groupée mixte : rapprochez toutes les paires demandées et ne réessayez que les échecs encore valides et de nouveau approuvés ; échouez en mode fermé face à un résultat manquant, dupliqué, contradictoire ou inattendu ;
résultat uniquement en quarantaine ordinaire : continuez avec /quarantine sans transférer le message dans la famille post-livraison.

L’automatisation reste ainsi liée au tenant, consciente de l’état et reproductible, sans confondre quarantaine ordinaire et post-livraison.