Automatiser les boîtes Sophos Email avec l’API
La Sophos Email Management API couvre tout le cycle de vie d’une boîte : rechercher l’inventaire, créer des boîtes seules ou par lot, modifier noms et relations, puis supprimer des objets. La séquence sûre est toujours lire, comparer l’état souhaité à l’état réel, effectuer un changement ciblé, puis relire. Un statut HTTP positif ne suffit pas pour les opérations en masse ou sur les relations.
Confirmer les prérequis et la propriété
Cet article suppose acquise l’introduction à Sophos Email Management API. L’authentification, la durée du jeton, la résolution du tenant et le choix de l’hôte régional sont traités dans Authentifier Sophos Email API et router vers le tenant. Tous les chemins ci-dessous nécessitent :
- l’URL de base régionale
${SOPHOS_API_HOST%/}/email/v1; Authorization: Bearer <access-token>,X-Tenant-ID: <tenant-uuid>et, pour JSON,Content-Type: application/json;- un UUID de boîte à la place de
{id}; - le contrat API actuel. Les schémas vérifiés ici proviennent d’Email Management API v1.4.0.
Avant toute écriture, désignez le système propriétaire de l’inventaire. La synchronisation d’annuaire reste la référence des objets synchronisés. L’API ne remplace pas cette propriété : une modification peut être écrasée ou refusée. La spécification documente 409 pour une boîte synchronisée lors du renommage, de la suppression individuelle et des changements d’alias ou de délégués. Modifiez alors l’annuaire source au lieu de forcer des variantes ou des tentatives API.
Inventorier et rechercher toutes les boîtes
GET /mailboxes renvoie items et pages, avec fromKey, nextKey, size et maxSize. pageSize accepte au plus 50 enregistrements. Encodez pages.nextKey dans l’URL et transmettez-le comme pageFromKey ; l’inventaire n’est complet que lorsque nextKey est absent. Limitez les clés répétées, le nombre de pages et la durée totale.
Une requête n’accepte qu’un paramètre de recherche : name, nameStartsWith, email, emailStartsWith, createdAfter, createdBefore, type, bulkSenderPrivilegeStatus, blocked, distributionListOwnedBy, alias, aliasesStartWith ou delegate. Les types sont user, distributionList, publicFolder et sharedMailbox ; les statuts sont neverRequested, approvalPending, approved, rejected et revoked. Ne combinez pas filtre exact et filtre de préfixe.
Conservez au minimum id, type, email, name, createdAt et blocked. aliases, delegates, distributionListOwners, bulkSenderPrivilege et policies peuvent aussi être présents. Cet inventaire contient des données personnelles : ne le journalisez pas sans filtrage.
Créer, lire et renommer des boîtes
| Tâche | Méthode et chemin | Contrat |
|---|---|---|
| Créer une boîte | POST /mailboxes | type, email et name obligatoires |
| En créer jusqu’à 10 | POST /mailboxes/bulk | tableau items obligatoire, maximum 10 |
| Lire une boîte | GET /mailboxes/{id} | UUID id, état actuel en réponse |
| Changer le nom | PATCH /mailboxes/{id} | name, 1–256 caractères |
À la création, email respecte le format e-mail et compte 4–320 caractères ; name en compte 1–256. type prend l’une des quatre valeurs ci-dessus. La création seule renvoie 201 ; 409 signale qu’une boîte ou un alias utilise déjà l’adresse. Ne contournez pas cela avec une adresse modifiée : retrouvez l’objet et réglez sa propriété.
La création en masse renvoie aussi 201 si seuls certains éléments sont créés. Rapprochez items et errors de chaque adresse demandée, conservez les UUID réussis et ne corrigez que les éléments en échec. Vérifiez ensuite chaque objet par GET /mailboxes/{id} sur type, email et name. Un renommage renvoie 201 ; le GET suivant doit présenter le name attendu.
Modifier alias, délégués et propriétaires de listes
Les trois relations utilisent les tableaux JSON add et remove, utilisables ensemble. Lisez d’abord pour éviter un delta vide ou déjà appliqué.
| Relation | Chemin | Maximum par add et remove |
|---|---|---|
| Alias | POST /mailboxes/{id}/aliases | 100 |
| Délégués | POST /mailboxes/{id}/delegates | 50 |
| Propriétaires de liste | POST /mailboxes/{id}/distribution-list-owners | 1 |
La dernière opération s’applique au type distributionList. Pour les trois, 200 peut indiquer une réussite partielle. Traitez entièrement added, removed, errors.failedToAdd et errors.failedToRemove, puis vérifiez le delta exact par GET dans aliases, delegates ou distributionListOwners. Ne retentez que les valeurs en échec après correction de leur cause, jamais toute la requête à l’aveugle.
Les erreurs courantes sont un alias déjà utilisé, un alias inexistant ou un délégué sans boîte correspondante. 400 vise la requête ou le schéma, 404 l’ID ou le contexte tenant, et 409, pour les opérations qui le documentent, la propriété de synchronisation.
Demander le privilège d’envoi en masse
POST /mailboxes/{id}/bulksender-privilege-request exige count entier, period égal à daily, weekly ou monthly, et purpose de 2–2048 caractères. Décrivez l’usage réel. Le contrat ne fixe aucune borne numérique supérieure pour count : n’en inventez pas.
La réponse 200 contient accepted. accepted: true confirme le dépôt, pas l’approbation. Suivez l’état par GET dans bulkSenderPrivilege.bulkSenderPrivilegeStatus. Ne déposez une nouvelle demande qu’après contrôle de l’état et du besoin métier.
Supprimer sans nouvelle tentative aveugle
La suppression individuelle utilise DELETE /mailboxes/{id}. La réponse 200 contient deleted ; cette même classe est documentée quand la boîte est introuvable. Contrôlez donc le booléen et relisez ensuite.
POST /mailboxes/delete supprime jusqu’à 20 UUID dans le tableau obligatoire items. La réponse 200 sépare items réussis et errors par id. Avant toute suppression, exportez UUID et adresse puis rapprochez-les d’un inventaire récent. Supprimez les objets synchronisés à leur source.
Ne retentez jamais à l’aveugle : après un délai dépassé ou une erreur inattendue, certaines ou toutes les boîtes peuvent déjà être supprimées. Vérifiez chaque UUID par GET ou dans Sophos Fusion (anciennement Sophos Central), reconstruisez réussite et échec par élément, puis ne renvoyez, après nouvelle validation, que les cibles encore présentes.
Limites, erreurs et validation de production
Sophos documente 10 000 requêtes par jour pour Create, Update et Delete, et 20 000 pour Get ; le guide indique que la limite horaire égale la limite quotidienne. Les changements de nom, alias, délégués et propriétaires comptent comme Update. Sur 429, suspendez l’exécution dans des limites définies ; n’augmentez pas la concurrence et ne rejouez pas automatiquement les mutations. Contactez Sophos Support pour davantage de quota.
Avant la production, validez : pagination complète et un filtre par requête ; limites de type, adresse, nom et tableaux avant envoi ; rapprochement par élément des réponses bulk et relationnelles ; GET ou rapprochement d’inventaire après chaque écriture ; traitement distinct de 400, 404, 409, 429 et 5xx ; aucun nouvel essai automatique de Delete ou autre opération non idempotente après un résultat incertain. L’API reste ainsi un outil d’automatisation, et non une deuxième source de vérité concurrente.