Primeros pasos con la API de gestión de Sophos Email

La API de gestión de Email es la interfaz de automatización por tenant para determinadas tareas de Sophos Email. Esta introducción explica cómo validar el contrato de la API y elegir la familia de operaciones adecuada. Los procedimientos detallados de escritura, cuarentena y clawback pertenecen a sus runbooks respectivos; una visión general no autoriza cambios.

Incorporar los requisitos previos

Antes de la primera petición de Email, hay que completar el flujo común de la API de Sophos Fusion: autenticar un service principal mediante OAuth2, identificar el tenant de destino y descubrir su host regional. Gestionar de forma segura las credenciales de la API de Sophos Fusion (antes Sophos Central) cubre la protección de credenciales, la solicitud del token, whoami, la resolución de tenants Partner y Enterprise y el diagnóstico común.

Este artículo utiliza exactamente tres valores ya validados:

• SOPHOS_ACCESS_TOKEN: token bearer OAuth2 de corta duración;
• SOPHOS_TENANT_ID: UUID del tenant de destino;
• SOPHOS_API_HOST: host regional completo de ese tenant.

El host global solo sirve para descubrir identidad y tenant. Las operaciones de Email se envían al host regional devuelto. No se deduce una región ni un tenant de un nombre visible. Los tokens, secretos de cliente y respuestas completas no deben aparecer en código, registros ni tickets.

Elegir la familia de operaciones

Sophos Fusion también presenta Message History mediante consultas XDR y la gestión de certificados S/MIME como APIs de Email. Tienen contratos y permisos propios. No se trasladan a ellas rutas, esquemas ni supuestos de las cuatro familias anteriores.

Transferir Message History a la XDR Query API

Para Message History, se continúa en la descripción general vigente de la XDR Query API. Es un servicio regional independiente, protegido mediante OAuth2 y con raíz /xdr-query/v1; no es una operación bajo /email/v1. Los permisos y errores de XDR se evalúan por separado de los supuestos de la Email Management API.

El ciclo debe quedar acotado: usar las operaciones documentadas de categorías y definiciones de consulta para descubrir una definición vigente, iniciar una ejecución mediante POST, consultar su estado, obtener los resultados cuando termine y cancelarla cuando sea necesario. Este artículo no proporciona ni inventa una consulta de Email. Antes de implementar, hay que revisar en la descripción vigente enlazada los esquemas de operación y respuesta aplicables al inicio, la inspección, los resultados y la cancelación.

Antes de construir una consulta, se abre el visor oficial del esquema de Email Message History. En el panel Table name se selecciona una tabla y después se revisan General info, Fields y Custom Types. Como orientación, el esquema actual de Email expone exactamente tres tablas detectables: xdr_xge_att_data, xdr_xge_url_data y xdr_xge_events. El visor en vivo sigue siendo la autoridad para campos y tipos; este artículo no duplica una lista de campos. Estas tablas del Data Lake no son esquemas de respuesta de /email/v1.

Antes de implementar, se elige la operación exacta en la descripción vigente de la API y se revisan método HTTP, ruta, esquema de petición, esquema de respuesta, permiso y límites documentados. No se inventan rutas ni se deriva una operación sustituyendo un sustantivo.

El itinerario continúa desde autenticación y routing de tenant hasta buzones, clawback, cuarentena, cuarentena post-delivery y S/MIME.

Construir el contrato de petición

La especificación revisada usa una URL base regional terminada en /email/v1. Toda petición del tenant requiere el token bearer y X-Tenant-ID; las llamadas JSON usan Content-Type: application/json. Al host validado solo se añade la ruta de producto documentada:

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

Antes de escribir en producción, se ejecuta una lectura inocua. GET /mailboxes es una operación de listado en la especificación revisada. pageSize=1 solo limita la primera respuesta; no demuestra que no existan más páginas:

RESPONSE_FILE=$(mktemp) || exit 1
trap 'rm -f "$RESPONSE_FILE"' EXIT
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' \
    --header 'Content-Type: application/json' \
    "$EMAIL_API_HOST/mailboxes?pageSize=1"
)

if [[ "$HTTP_STATUS" != "200" ]]; then
  printf 'Email API returned HTTP %s\n' "$HTTP_STATUS" >&2
  exit 1
fi

if ! jq -e '(.items | type) == "array" and (.pages | type) == "object"' \
  "$RESPONSE_FILE" >/dev/null; then
  printf 'Email API response failed schema validation\n' >&2
  exit 1
fi
rm -f "$RESPONSE_FILE"
trap - EXIT

La prueba es correcta si el estado es 200 y existen las estructuras items y pages. No se registran indiscriminadamente los cuerpos: incluso una lista de buzones contiene datos personales del tenant.

Contemplar la paginación, la limitación de tasa y la duración del token

Una primera página correcta no constituye un inventario completo. En GET /mailboxes, pages.nextKey contiene la clave siguiente; se envía codificada para URL como pageFromKey en la petición posterior. El cliente continúa hasta que no haya nextKey, con límites de páginas y tiempo y detección de claves repetidas. Para cualquier otra operación solo rige su modelo de paginación vigente.

La limitación de tasa no es un error de esquema. Ante 429, se respetan las cabeceras documentadas de reintento o de límite de tasa, se usa una espera acotada con jitter y se limita el número y la duración de los intentos. No se reintentan a ciegas escrituras, eliminaciones, liberaciones ni clawbacks: el timeout puede ocurrir después de que el servidor acepte la operación.

Un token caducado se renueva mediante OAuth2. Un 401 no se elude cambiando tenant o región. Ante 403, se comprueban rol, permiso y asignación; ante 404, host regional, ruta documentada e ID. Los demás 4xx son errores de petición o estado. Los 5xx se tratan de forma acotada, aclarando estado y posible efecto antes de reintentar.

Validar versión y paso a producción

La especificación en la que se basa este artículo se revisó en la versión v1.4.0. Hay que verificar de nuevo la versión vigente antes de implementar. Las rutas o esquemas de v1.4.0 no son una promesa para versiones posteriores.

Antes de autorizar la puesta en producción, se documentan:

1. propietario de credenciales, rol mínimo, ID del tenant y host regional descubierto;
2. familia elegida y método, ruta y esquema vigentes;
3. GET inocuo con estado HTTP y resultado del esquema, sin token ni payload completo;
4. fin de paginación, tratamiento de 429, renovación de token y duración máxima de reintentos;
5. para cada cambio, idempotencia, aprobación, efecto esperado, validación y vía de parada.

La operación de negocio se implementa solo después de superar estos controles en un tenant de prueba o registro controlado. OAuth2 y el enrutamiento del tenant siguen siendo requisitos comunes, no funciones de Sophos Email.