Gestionar la cuarentena posterior a la entrega de Sophos Email mediante API

La cuarentena posterior a la entrega contiene mensajes que primero se entregaron y que Post-Delivery Protection retiró después del buzón. Por eso su API utiliza la familia de rutas independiente /post-delivery-quarantine. Los endpoints de nombre parecido bajo /quarantine corresponden a la cuarentena ordinaria anterior a la entrega y no son intercambiables.

La secuencia segura consiste en buscar con criterios precisos, verificar el resultado y el destinatario, inspeccionar el mensaje o sus adjuntos, modificar únicamente los ID autorizados y volver a consultar el estado. Introducción a Email Management API sitúa las familias de API. Preparar OAuth2, el tenant y el enrutamiento regional proporciona los valores de acceso utilizados aquí.

Establecer los requisitos y la base de las solicitudes

Antes de la primera llamada, Post-Delivery Protection debe estar habilitada para el dominio afectado, debe existir un service principal y se debe confirmar su permiso para Post-Delivery Quarantine. Del flujo de autenticación solo se toman estos valores ya validados:

SOPHOS_ACCESS_TOKEN: token Bearer vigente;
SOPHOS_TENANT_ID: UUID del tenant de destino;
SOPHOS_API_HOST: host regional descubierto para ese tenant concreto.

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

Cada llamada envía el encabezado Authorization con Bearer seguido del SOPHOS_ACCESS_TOKEN vigente, el encabezado X-Tenant-ID con el valor SOPHOS_TENANT_ID y Accept: application/json; las solicitudes JSON también envían Content-Type: application/json. El tenant, el token y el host regional deben corresponderse. Un 403 se resuelve comprobando el permiso de API y la asignación del tenant, no probando otros tenants. Los ejemplos se basan en Email Management API v1.4.0; compruebe de nuevo el contrato vigente antes de implementarlos.

Buscar mensajes posteriores a la entrega con precisión

POST /post-delivery-quarantine/messages/search requiere las marcas de tiempo beginDate y endDate. Son opcionales page (desde 1), pageSize (50 de forma predeterminada, 100 como máximo), sort y filter. Los filtros documentados son id, fromContains, toContains, subjectContains, attachmentNameContains, sizeInMBGreaterThan, sizeInMBLowerThan, productType, reason y hasAnyAttachment. productType admite mailflow, gateway o ems; reason admite malware, maliciousUrl u onDemand.

Inicie una investigación controlada con un intervalo UTC corto y datos conocidos:

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

Sustituya la hora y la dirección de ejemplo por el alcance autorizado de la investigación. La respuesta contiene items y pages. Empiece en la página 1 e incremente page exactamente en uno. Si existe pages.total, deténgase al alcanzar ese total; en caso contrario, deténgase en la primera página vacía o que contenga menos elementos que el pageSize solicitado. Defina antes de empezar límites máximos de páginas y de tiempo de ejecución, y marque la búsqueda como incompleta si la paginación es incorrecta, se repite, no avanza o se alcanza uno de esos límites. Antes de modificar nada, compare como mínimo id, forRecipient, quarantinedAt, reason, el asunto y el tenant esperado. id es el valor del encabezado MIME X-Sophos-Email-ID, no el Message-ID MIME ni o365MessageId.

Inspeccionar el contenido y los adjuntos

Hay dos operaciones de lectura para cada id encontrado:

GET /post-delivery-quarantine/messages/{id}/preview devuelve headers y, si existen, htmlBody y textBody.
GET /post-delivery-quarantine/messages/{id}/attachments?page=1&pageSize=50 devuelve nombres de adjuntos y sizeInBytes junto con pages. Los valores predeterminados son la página 1 y 50 elementos; la respuesta admite hasta 500 elementos por página.

La vista previa puede contener contenido malicioso y confidencial. No renderice activamente el HTML, no abra enlaces ni registre respuestas sin filtrar. La operación de listado todavía no descarga ningún archivo.

Para descargar, envíe los nombres de los adjuntos deseados a POST /post-delivery-quarantine/messages/{id}/attachments/download. Si se omite attachments, el trabajo descarga todos los adjuntos; por ello conviene indicar una lista explícita:

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

La respuesta contiene un id de trabajo y status. Ese id se convierte en downloadId para:

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

Mientras status sea processing, consulte con un intervalo limitado. Con completed, la respuesta contiene los nombres y url; también puede aparecer password para un ZIP protegido. Con failed, examine error en vez de reiniciar indefinidamente la misma solicitud. Abra los archivos solo en un entorno de análisis aislado y no incluya la URL ni la contraseña en registros o tickets.

Liberar o eliminar

Ambas operaciones de escritura aceptan como máximo 50 elementos en items. Cada elemento necesita el id posterior a la entrega; forRecipients limita la acción a destinatarios concretos. Si se omite forRecipients, la guía aplica la acción a todos los destinatarios del mensaje.

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

POST /post-delivery-quarantine/messages/release pone uno o varios mensajes en cola para liberarlos. HTTP 202 significa aceptado, no confirmado en el buzón.
POST /post-delivery-quarantine/messages/delete elimina uno o varios mensajes de Post-Delivery Quarantine. La especificación revisada devuelve HTTP 200 cuando tiene éxito; por tanto, esta eliminación no se trata como un trabajo de descarga.

Antes de liberar, documente el contenido, el alcance de destinatarios y la autorización. Conserve o exporte las pruebas necesarias para la investigación antes de cualquiera de las operaciones de escritura. Un delete correcto no dispone de ninguna operación de API documentada para deshacerlo o restaurarlo; exija la aprobación de la eliminación y eleve cualquier duda antes de ese paso irreversible. Un release vuelve a entregar el mensaje, pero no permite repetir la retirada original del buzón. No repita a ciegas tras un timeout o 5xx: el efecto en el servidor podría haberse producido.

Validar resultados y errores parciales

Liberación y eliminación devuelven arrays separados items y errors. Antes de enviarla, expanda la solicitud autorizada en pares concretos (id, recipient) y concilie cada par solicitado exactamente una vez entre ambos arrays: una entrada correcta de items contiene solo id y recipient, mientras que una entrada fallida de errors contiene id, recipient y error. Considere la respuesta no válida y falle de forma cerrada si falta un par solicitado, está duplicado, aparece en ambos arrays o se devuelve un par no solicitado. Registre el resultado y el error devuelto para cada par, sin contenido ni tokens. Reintente solo los pares fallidos que sigan siendo válidos tras comprobar el estado y vuelvan a estar autorizados; nunca reintente pares correctos o ambiguos.

Busque después el mismo id y destinatario en Post-Delivery Quarantine. Tras una eliminación correcta, el elemento ya no debe aparecer en el alcance elegido; esta validación confirma el resultado destructivo, no una vía de recuperación. Tras aceptar una liberación, espere al cambio de estado y confirme además en el buzón de destino que el mensaje reapareció para el destinatario previsto. Esa confirmación de entrega no demuestra que se pueda repetir la retirada original. Si el elemento permanece en la búsqueda o el mensaje falta en el buzón, revise destinatario, estado de PDP y error devuelto antes de volver a evaluar esa parte.

Estas distinciones ayudan a diagnosticar problemas:

sin resultados: compruebe intervalo UTC, página, tenant, tipo de ID y estado de PDP;
404 en vista previa, adjuntos o trabajo: compruebe host regional, ruta post-delivery e ID correspondiente;
descarga failed: examine error y compare los nombres con la lista actual;
respuesta masiva mixta: concilie todos los pares solicitados y reintente solo los pares fallidos aún válidos y nuevamente autorizados; falle de forma cerrada ante resultados ausentes, duplicados, contradictorios o inesperados;
resultado solo en cuarentena ordinaria: continúe con /quarantine; no traslade el mensaje a la familia post-delivery.

Así la automatización permanece vinculada al tenant, consciente del estado y repetible, sin confundir la cuarentena ordinaria con la posterior a la entrega.