Automatizzare le caselle Sophos Email tramite API

La Sophos Email Management API copre l’intero ciclo di vita delle caselle: ricerca nell’inventario, creazione singola o in blocco, modifica di nomi e relazioni ed eliminazione. La sequenza sicura è sempre leggere, confrontare stato desiderato e reale, applicare una modifica mirata e rileggere. Un esito HTTP positivo non basta per operazioni bulk o sulle relazioni.

Verificare prerequisiti e titolarità

Questo articolo presuppone l’introduzione alla Sophos Email Management API. Autenticazione, durata del token, risoluzione del tenant e host regionale sono descritti in Autenticare Sophos Email API e instradare verso il tenant. Tutti i percorsi seguenti richiedono:

• URL base regionale ${SOPHOS_API_HOST%/}/email/v1;
• Authorization: Bearer <access-token>, X-Tenant-ID: <tenant-uuid> e, per body JSON, Content-Type: application/json;
• UUID della casella dove compare {id};
• contratto API corrente. Gli esempi si riferiscono a Email Management API v1.4.0.

Prima di scrivere, stabilisci quale sistema possiede l’inventario. La sincronizzazione directory rimane autorevole per gli oggetti sincronizzati. L’API non sostituisce questa titolarità: una modifica può essere sovrascritta o rifiutata. La specifica documenta 409 per una casella sincronizzata durante rinomina, eliminazione singola e modifica di alias o delegati. Intervieni nella directory sorgente, senza forzare varianti o ritentare via API.

Inventariare e cercare tutte le caselle

GET /mailboxes restituisce items e pages con fromKey, nextKey, size e maxSize. pageSize supporta al massimo 50 record. Codifica per URL pages.nextKey e invialo come pageFromKey; l’inventario termina solo in assenza di nextKey. Limita chiavi ripetute, pagine e durata totale.

È ammesso un solo parametro di ricerca per richiesta: name, nameStartsWith, email, emailStartsWith, createdAfter, createdBefore, type, bulkSenderPrivilegeStatus, blocked, distributionListOwnedBy, alias, aliasesStartWith o delegate. I tipi sono user, distributionList, publicFolder e sharedMailbox; gli stati sono neverRequested, approvalPending, approved, rejected e revoked. Non combinare filtri esatti e per prefisso.

Conserva almeno id, type, email, name, createdAt e blocked. Possono comparire anche aliases, delegates, distributionListOwners, bulkSenderPrivilege e policies. L’inventario contiene dati personali e non va registrato integralmente nei log.

Creare, leggere e rinominare caselle

In creazione, email ha formato e-mail e 4–320 caratteri; name ne ha 1–256. type accetta i quattro valori sopra. La creazione singola restituisce 201; 409 indica che una casella o un alias usa già l’indirizzo. Non aggirare il conflitto alterando l’indirizzo: trova l’oggetto e chiariscine la titolarità.

Anche la creazione bulk restituisce 201 quando riesce solo in parte. Riconcilia items ed errors con ogni indirizzo richiesto, conserva gli UUID riusciti e correggi soltanto gli elementi falliti. Verifica ogni oggetto con GET /mailboxes/{id} confrontando type, email e name. La rinomina restituisce 201; il GET seguente deve mostrare il name atteso.

Modificare alias, delegati e proprietari di liste

Le tre relazioni usano array JSON add e remove, anche insieme. Leggi prima per evitare delta vuoti o già soddisfatti.

L’ultima operazione vale per distributionList. In tutti e tre i casi, 200 può indicare successo parziale. Valuta added, removed, errors.failedToAdd ed errors.failedToRemove, quindi verifica con GET il delta esatto in aliases, delegates o distributionListOwners. Ritenta solo i valori falliti dopo averne risolto la causa, mai l’intera richiesta alla cieca.

Errori tipici sono un alias già utilizzato, un alias inesistente o un delegato senza casella. 400 riguarda richiesta o schema, 404 ID o contesto tenant e 409, dove documentato, la titolarità della sincronizzazione.

Richiedere il privilegio di mittente massivo

POST /mailboxes/{id}/bulksender-privilege-request richiede count intero, period pari a daily, weekly o monthly e purpose di 2–2048 caratteri. Descrivi l’uso reale. Il contratto non specifica un limite numerico massimo per count: non inventarne uno.

La risposta 200 contiene accepted. accepted: true conferma l’invio, non l’approvazione. Segui lo stato con GET in bulkSenderPrivilege.bulkSenderPrivilegeStatus. Presenta una nuova richiesta solo dopo aver controllato stato e motivazione.

Eliminare senza ritentare alla cieca

L’eliminazione singola usa DELETE /mailboxes/{id}. La risposta 200 contiene deleted; la stessa classe è documentata anche se la casella non viene trovata. Controlla quindi il booleano e rileggi.

POST /mailboxes/delete elimina fino a 20 UUID nell’array obbligatorio items; la risposta 200 separa items riusciti ed errors per id. Prima di eliminare, esporta UUID e indirizzo e riconciliali con un inventario recente. Rimuovi gli oggetti sincronizzati alla sorgente.

Mai ritentare alla cieca: dopo timeout o errore imprevisto, alcune o tutte le caselle potrebbero essere già eliminate. Controlla ogni UUID tramite GET o Sophos Fusion (in precedenza Sophos Central), ricostruisci esiti per elemento e, dopo nuova approvazione, invia solo obiettivi ancora presenti.

Limiti, errori e approvazione per la produzione

Sophos documenta 10.000 richieste giornaliere per Create, Update e Delete e 20.000 per Get; la guida afferma che il limite orario coincide con quello giornaliero. Modifiche a nome, alias, delegati e proprietari contano come Update. Con 429, sospendi entro limiti definiti; non aumentare la concorrenza né ripetere automaticamente mutazioni. Per più quota contatta Sophos Support.

Prima della produzione verifica: paginazione completa e un filtro per richiesta; limiti di tipo, e-mail, nome e array prima dell’invio; riconciliazione per elemento delle risposte bulk e relazionali; GET o inventario dopo ogni scrittura; gestione distinta di 400, 404, 409, 429 e 5xx; nessun retry automatico di Delete o altre operazioni non idempotenti dopo un esito incerto. Così l’API resta uno strumento di automazione, non una seconda fonte di verità concorrente.