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 schemi verificati qui provengono da 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 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.