Bien démarrer avec l’API Sophos Email Management

L’API Email Management est l’interface d’automatisation limitée au tenant pour certaines tâches Sophos Email. Cette introduction explique comment valider le contrat d’API et choisir la bonne famille d’opérations. Les procédures détaillées d’écriture, de quarantaine et de clawback restent dans leurs runbooks respectifs ; une vue d’ensemble n’autorise aucun changement.

Reprendre les prérequis

Avant la première requête Email, il faut terminer le parcours commun des API Sophos Fusion : authentifier un service principal avec OAuth2, identifier le tenant cible et découvrir son hôte régional. Gérer en toute sécurité les identifiants d’API Sophos Fusion (anciennement Sophos Central) couvre la protection des identifiants, la demande de jeton, whoami, la résolution des tenants Partner et Enterprise et le diagnostic partagé.

Cet article reprend exactement trois valeurs validées :

SOPHOS_ACCESS_TOKEN : jeton bearer OAuth2 de courte durée ;
SOPHOS_TENANT_ID : UUID du tenant cible ;
SOPHOS_API_HOST : hôte régional complet de ce tenant.

L’hôte global sert uniquement à découvrir l’identité et le tenant. Les opérations Email utilisent l’hôte régional retourné. Ne jamais déduire une région ou un tenant d’un nom d’affichage. Jetons, secrets client et réponses complètes ne doivent figurer ni dans le code, ni dans les journaux, ni dans les tickets.

Choisir la famille d’opérations

Objectif	Famille	À établir d’abord
Inventorier ou gérer les boîtes aux lettres	Mailbox Management	source des données, types autorisés et éventuelle propriété de la synchronisation d’annuaire
Examiner ou traiter des messages retenus avant livraison	Quarantine	filtres, sélection, autorisation et effet d’une libération, suppression ou action sur pièce jointe
Examiner ou traiter des messages déjà livrés	Post-Delivery Quarantine	protection post-livraison active, état actuel et éventuels travaux asynchrones
Rappeler un message livré et suivre le résultat	Clawback	ID de message admissible, périmètre des destinataires, autorisation et état asynchrone

Sophos Fusion présente aussi Message History via des requêtes XDR et la gestion des certificats S/MIME comme API Email. Leurs contrats et autorisations sont distincts. Ne pas leur appliquer les chemins, schémas ou hypothèses des quatre familles ci-dessus.

Transmettre Message History à l’API XDR Query

Pour Message History, poursuivre avec la présentation actuelle de l’API XDR Query. Il s’agit d’un service régional distinct, protégé par OAuth2 et basé sur /xdr-query/v1, et non d’une opération sous /email/v1. Évaluer les autorisations et erreurs XDR indépendamment des hypothèses relatives à l’API Email Management.

Le cycle de vie doit rester borné : utiliser les opérations documentées de catégorie et de définition de requête pour trouver une définition actuelle, lancer une exécution avec POST, examiner son état, récupérer ses résultats lorsqu’elle est terminée et l’annuler si nécessaire. Cet article ne fournit ni n’invente de requête Email. Avant l’implémentation, vérifier dans la description d’API actuelle liée les schémas d’opération et de réponse applicables au lancement, au suivi, aux résultats et à l’annulation.

Avant de construire une requête, ouvrir le visualiseur officiel du schéma Email Message History. Sélectionner une table dans le volet Table name, puis examiner General info, Fields et Custom Types. À titre de repère, le schéma Email actuel expose exactement trois tables détectables : xdr_xge_att_data, xdr_xge_url_data et xdr_xge_events. Le visualiseur en ligne reste la référence pour les champs et les types ; cet article ne reproduit volontairement aucune liste de champs. Ces tables Data Lake ne sont pas des schémas de réponse de /email/v1.

Avant toute implémentation, sélectionner l’opération exacte dans la description d’API actuelle et vérifier sa méthode HTTP, son chemin, les schémas de requête et de réponse, l’autorisation et les limites documentées. Ne jamais inventer un chemin ni déduire une opération en remplaçant un nom.

Le parcours mène de l’authentification et du routage tenant aux boîtes aux lettres, au clawback, à la quarantaine, à la quarantaine post-delivery et à S/MIME.

Construire le contrat de requête

La spécification examinée utilise une URL de base régionale terminée par /email/v1. Toute requête liée au tenant nécessite le jeton bearer et X-Tenant-ID ; les appels JSON emploient Content-Type: application/json. Ajouter uniquement le chemin produit documenté à l’hôte déjà validé :

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

Effectuer une lecture sans effet avant toute écriture en production. GET /mailboxes est une opération de liste dans la spécification examinée. pageSize=1 limite seulement la première réponse et ne prouve pas l’absence d’autres pages :

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

Le test réussit si le statut est 200 et si les structures items et pages sont présentes. Ne pas journaliser les corps sans filtrage : même une liste de boîtes contient des données personnelles du tenant.

Gérer pagination, limitation et durée du jeton

Une première page valide n’est pas un inventaire complet. Pour GET /mailboxes, pages.nextKey fournit la clé de la page suivante ; elle est transmise, encodée pour l’URL, dans pageFromKey à la requête suivante. Le client continue jusqu’à l’absence de nextKey, tout en limitant pages et durée et en détectant les clés répétées. Pour toute autre opération, seul son modèle de pagination actuellement documenté s’applique.

La limitation de débit n’est pas une erreur de schéma. Sur 429, respecter les en-têtes documentés de nouvelle tentative ou de débit, appliquer un backoff borné avec jitter et limiter les tentatives et leur durée totale. Ne pas relancer aveuglément écriture, suppression, libération ou clawback : un délai d’attente peut survenir après acceptation par le serveur.

Renouveler un jeton expiré via OAuth2. Ne pas contourner 401 en changeant de tenant ou de région. Sur 403, vérifier rôle, autorisation et affectation au tenant ; sur 404, hôte régional, chemin documenté et ID d’objet. Les autres 4xx indiquent une erreur de requête ou d’état. Pour 5xx, borner le traitement et établir l’état et l’effet possible avant une relance contrôlée.

Valider la version et la mise en production

La spécification qui fonde cet article a été examinée en v1.4.0. Vérifier à nouveau la version actuelle avant l’implémentation. Les chemins ou schémas de v1.4.0 ne constituent pas une promesse pour les versions ultérieures.

Avant la mise en production, consigner :

propriétaire des identifiants, rôle minimal, ID du tenant et hôte régional découvert ;
famille choisie et méthode, chemin et schéma actuels ;
test GET sans effet avec statut HTTP et résultat de schéma, sans jeton ni payload complet ;
fin de pagination, comportement 429, renouvellement du jeton et durée maximale des relances ;
pour chaque mutation, idempotence, approbation, effet attendu, validation et procédure d’arrêt.

N’implémenter l’opération métier qu’après validation de ces contrôles dans un tenant de test ou sur un enregistrement contrôlé. OAuth2 et le routage du tenant restent des prérequis partagés ; ce ne sont pas des fonctions Sophos Email.