Ir al contenido
Avanet

Ejecutar y verificar clawback de Sophos Email mediante API

Sophos Email

La API de Clawback retira mensajes de Sophos Email ya entregados en buzones aptos. El flujo seguro tiene dos fases: enviar una sola vez la solicitud y consultar GET /messages/{id}/status hasta obtener un resultado terminal para cada destinatario aceptado. Una respuesta 202 confirma que se aceptó el trabajo, no que se completó en el buzón.

Confirmar requisitos y límites

Antes del primer clawback hacen falta un service principal configurado, un token bearer OAuth2 válido, el UUID del tenant y su host regional descubierto. La introducción a Email Management API explica las familias y la lectura segura. El runbook previsto Autenticación y enrutamiento de tenant para la API de Sophos Email reúne token, resolución del tenant y región.

Los ejemplos usan variables ya validadas:

EMAIL_API_HOST="${SOPHOS_API_HOST%/}/email/v1"
SOPHOS_EMAIL_ID="15a7f8ea-691c-4f03-862e-3cefb102818e"

SOPHOS_API_HOST es el host regional descubierto, no uno deducido. Sustituya el ejemplo inocuo SOPHOS_EMAIL_ID. Toda petición usa Authorization: Bearer *** y X-Tenant-ID; no incluya secretos ni datos completos del mensaje en código, registros o tickets.

También se requiere la autorización PDP/clawback correspondiente y una conexión operativa con el proveedor. Solo pueden remediarse mensajes entregados correctamente a buzones aptos y destinatarios aptos. Post-Delivery Protection en Sophos Fusion cubre la conexión, On demand clawback en la interfaz y Auto search and remediate. Son flujos distintos de la API y no sustituyen su consulta de estado.

Obtener el x-sophos-email-id correcto

El parámetro {id} es el valor de la cabecera MIME X-Sophos-Email-ID, no el Message-ID de Internet, el asunto ni cualquier UUID. Sophos también indica que puede derivarse de distintas respuestas de consultas Email en Live Discover de Threat Analysis Center. Este runbook no inventa un esquema: obtenga x-sophos-email-id de evidencia fiable y confirme como mínimo tenant, mensaje y destinatarios afectados.

Asigne el valor a SOPHOS_EMAIL_ID sin espacios ni saltos de línea. Para varios mensajes, registre cada ID con su aprobación y caso; no prepare una lista solo por asuntos similares.

Retirar un mensaje

El endpoint documentado es POST /messages/{id}/clawback. Si se omite recipients, Sophos lo intenta para todos los destinatarios. Use ese alcance amplio solo si todos pertenecen al incidente. Para un piloto, indique las direcciones; la especificación admite hasta 500.

El reason opcional es malware, phishing, spam o unwanted:

{
  "reason": "phishing",
  "recipients": [
    "user1@example.com",
    "user2@example.com"
  ]
}

Envíe el POST una sola vez y proteja la respuesta:

REQUEST_FILE=$(mktemp) || exit 1
RESPONSE_FILE=$(mktemp) || exit 1
trap 'rm -f "$REQUEST_FILE" "$RESPONSE_FILE"' EXIT

cat >"$REQUEST_FILE" <<'JSON'
{
  "reason": "phishing",
  "recipients": ["user1@example.com", "user2@example.com"]
}
JSON

HTTP_STATUS=$(
  printf 'header = "Authorization: Bearer %s"\n' "$SOPHOS_ACCESS_TOKEN" |
  curl --silent --show-error --config - \
    --output "$RESPONSE_FILE" \
    --write-out '%{http_code}' \
    --request POST \
    --header "X-Tenant-ID: $SOPHOS_TENANT_ID" \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-binary "@$REQUEST_FILE" \
    "$EMAIL_API_HOST/messages/$SOPHOS_EMAIL_ID/clawback"
)
printf 'Clawback submission returned HTTP %s\n' "$HTTP_STATUS"

Se espera 202. La respuesta separa recipients aceptados de errors, cada uno con recipient y error. Registre la aceptación por destinatario sin exponer toda la respuesta. Sophos describe la llamada individual limitada por destinatarios como atómica: un destinatario no apto puede hacer fallar toda la petición. Compruebe la causa, elimínelo solo con justificación y envíe después una nueva petición deliberada.

Retirar varios mensajes

Para varios mensajes, Sophos documenta POST /messages/clawback con una lista messageIds. Cada elemento es un x-sophos-email-id:

{
  "messageIds": [
    "e4fa988e-76f6-11ee-b962-0242ac120002",
    "eb9df47e-76f6-11ee-b962-0242ac120002",
    "ef790f0276f611eeb9620242ac120002"
  ]
}

La llamada múltiple reduce peticiones, no verificaciones. Registre aceptación y estado para cada ID. Si solo afectan algunos destinatarios de un mensaje, use el endpoint individual con recipients; el payload múltiple documentado no incluye destinatarios.

Consultar hasta el resultado terminal por destinatario

Para cada ID use GET /messages/{id}/status. Bajo items aparecen recipient y status:

{
  "items": [
    {"recipient": "user1@example.com", "status": "clawbackSuccessful"},
    {"recipient": "user2@example.com", "status": "clawbackFailed"}
  ]
}

clawbackProcessing es intermedio. Registre clawbackSuccessful o clawbackFailed como resultado terminal de cada destinatario. El esquema también puede devolver accepted, quarantined, deliverySuccessful o deliveryFailed; no los interprete como éxito del clawback.

HTTP_STATUS=$(
  printf 'header = "Authorization: Bearer %s"\n' "$SOPHOS_ACCESS_TOKEN" |
  curl --silent --show-error --config - \
    --output "$RESPONSE_FILE" \
    --write-out '%{http_code}' \
    --request GET \
    --header "X-Tenant-ID: $SOPHOS_TENANT_ID" \
    --header 'Accept: application/json' \
    "$EMAIL_API_HOST/messages/$SOPHOS_EMAIL_ID/status"
)
printf 'Clawback status returned HTTP %s\n' "$HTTP_STATUS"

Consulte con intervalo limitado y jitter mientras falte algún resultado terminal. Limite intentos y duración total. Al agotarse el tiempo, el resultado es desconocido, no fallido: no envíe otro POST hasta que un GET posterior o Sophos Fusion aclare el efecto del primero.

Gestionar con seguridad resultados parciales y errores

  • No apto o ya remediado: compruebe mensaje, dominio, entrega y destinatario. Repetir POST no repara un éxito previo. Tras un rechazo atómico, quite direcciones no aptas solo después de comprobarlas.
  • Estados mixtos: conserve clawbackSuccessful para éxitos e investigue clawbackFailed aparte. No marque todo como correcto ni vuelva a procesar éxitos.
  • 400: revise ID, JSON, reason permitido y destinatarios; no repita sin cambios.
  • 401 o 403: renueve mediante OAuth2 o revise rol, permiso clawback y asignación al tenant. No cambie tenant o región a modo de prueba.
  • 404: compare host regional, ruta documentada y x-sophos-email-id con la evidencia.
  • Limitación (429): respete indicaciones documentadas y ralentice los GET con backoff limitado y jitter. Nunca repita un POST a ciegas.
  • Timeout o 5xx: puede haberse aceptado en el servidor. Consulte primero el mismo ID, limite intentos y tiempo, y reenvíe solo cuando se conozca el efecto.

La validación termina cuando quedan registrados el resultado de envío, destinatarios aceptados y rechazados y cada resultado terminal para cada ID. Como control adicional, revise el buzón y Post-Delivery Quarantine del tenant correcto. La respuesta API sigue siendo la base legible por máquina; clawback en UI, PDP automático e informes son rutas operativas separadas.