Introduzione alla Sophos Email Management API

La Email Management API è l’interfaccia di automazione circoscritta al tenant per determinate attività di Sophos Email. Questa introduzione spiega come verificare il contratto API e scegliere la famiglia di operazioni corretta. Le procedure dettagliate di scrittura, quarantena e clawback restano nei rispettivi runbook; una panoramica non autorizza modifiche.

Acquisire i prerequisiti

Prima della prima richiesta Email occorre completare il flusso API Sophos Fusion comune: autenticare un service principal tramite OAuth2, identificare il tenant di destinazione e scoprirne l’host API regionale. Gestire in modo sicuro le credenziali API Sophos Fusion (in precedenza Sophos Central) descrive protezione delle credenziali, richiesta del token, whoami, risoluzione dei tenant Partner ed Enterprise e diagnostica comune.

Questo articolo usa esattamente tre valori già convalidati:

SOPHOS_ACCESS_TOKEN: token bearer OAuth2 di breve durata;
SOPHOS_TENANT_ID: UUID del tenant di destinazione;
SOPHOS_API_HOST: host regionale completo per quel tenant.

L’host globale serve solo a scoprire identità e tenant. Le operazioni Email vanno inviate all’host regionale restituito. Non dedurre regione o tenant da un nome visualizzato. Token, client secret e payload completi non devono finire in codice, log o ticket.

Scegliere la famiglia di operazioni

Obiettivo	Famiglia	Verificare prima
Inventariare o gestire cassette postali	Mailbox Management	origine dei dati, tipi consentiti e se la sincronizzazione directory ne è proprietaria
Esaminare o gestire messaggi trattenuti prima della consegna	Quarantine	filtri, selezione, autorizzazione ed effetto di rilascio, eliminazione o azioni sugli allegati
Esaminare o gestire messaggi già consegnati	Post-Delivery Quarantine	protezione post-delivery attiva, stato corrente ed eventuali job asincroni
Richiamare un messaggio consegnato e seguirne l’esito	Clawback	ID messaggio idoneo, ambito destinatari, autorizzazione e stato asincrono

Sophos Fusion presenta come API Email anche Message History tramite query XDR e la gestione dei certificati S/MIME. Hanno contratti e autorizzazioni distinti. Non trasferire a esse percorsi, schemi o ipotesi delle quattro famiglie precedenti.

Passare Message History alla XDR Query API

Per Message History, proseguire con la panoramica corrente della XDR Query API. È un servizio regionale separato, protetto da OAuth2 e con radice /xdr-query/v1, non un’operazione sotto /email/v1. Valutare autorizzazioni ed errori XDR separatamente dalle ipotesi della Email Management API.

Mantenere limitato il ciclo di vita: usare le operazioni documentate per categorie e definizioni di query per individuare una definizione corrente, avviare un’esecuzione con POST, esaminarne lo stato, recuperarne i risultati al termine e annullarla quando necessario. Questo articolo non fornisce né inventa una query Email. Prima dell’implementazione, verificare nella descrizione API corrente collegata gli schemi di operazione e risposta applicabili ad avvio, controllo, risultati e annullamento.

Prima di costruire una query, aprire il visualizzatore ufficiale dello schema Email Message History. Selezionare una tabella nel riquadro Table name, quindi esaminare General info, Fields e Custom Types. Come orientamento, lo schema Email corrente espone esattamente tre tabelle rilevabili: xdr_xge_att_data, xdr_xge_url_data e xdr_xge_events. Il visualizzatore live resta l’autorità per campi e tipi; questo articolo non duplica intenzionalmente un elenco di campi. Queste tabelle del Data Lake non sono schemi di risposta di /email/v1.

Prima di implementare, scegliere l’operazione esatta nella descrizione API corrente e verificarne metodo HTTP, percorso, schema di richiesta, schema di risposta, autorizzazione e limiti documentati. Non inventare percorsi né ricavare un’operazione sostituendo un sostantivo.

Il percorso prosegue da autenticazione e routing tenant a mailbox, clawback, quarantena, quarantena post-delivery e S/MIME.

Costruire il contratto della richiesta

La specifica esaminata usa un URL di base regionale che termina con /email/v1. Ogni richiesta relativa al tenant richiede token bearer e X-Tenant-ID; le chiamate JSON usano Content-Type: application/json. Aggiungere all’host convalidato solo il percorso prodotto documentato:

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

Prima delle scritture in produzione eseguire una lettura innocua. GET /mailboxes è un’operazione di elenco nella specifica esaminata. pageSize=1 limita solo la prima risposta e non dimostra che non esistano altre pagine:

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

Il test riesce con stato 200 e strutture items e pages presenti. Non registrare indiscriminatamente i corpi: anche l’elenco delle cassette contiene dati personali del tenant.

Gestire paginazione, throttling e durata del token

Una prima pagina valida non è un inventario completo. Per GET /mailboxes, pages.nextKey contiene la chiave successiva; nella richiesta seguente va passata, codificata per URL, come pageFromKey. Il client continua finché non resta alcun nextKey, limitando pagine e durata e rilevando chiavi ripetute. Per ogni altra operazione vale solo il modello di paginazione attualmente documentato.

Il throttling non è un errore di schema. Con 429, rispettare gli header documentati di retry o rate limit, usare un backoff limitato con jitter e porre un limite a tentativi e durata totale. Non ripetere alla cieca scritture, eliminazioni, rilasci o clawback: un timeout può verificarsi dopo l’accettazione server.

Rinnovare un token scaduto tramite OAuth2. Non aggirare 401 cambiando tenant o regione. Con 403, controllare ruolo, autorizzazione e assegnazione; con 404, host regionale, percorso documentato e ID. Gli altri 4xx sono errori di richiesta o stato. Gestire i 5xx entro limiti precisi e chiarire stato ed eventuale effetto prima di riprovare.

Convalidare versione e rilascio in produzione

La specifica alla base di questo articolo è stata esaminata alla versione v1.4.0. Verificare nuovamente la versione corrente prima dell’implementazione. Percorsi o schemi di v1.4.0 non sono garantiti per le versioni successive.

Prima del rilascio documentare:

proprietario delle credenziali, ruolo minimo, ID tenant e host regionale scoperto;
famiglia scelta e metodo, percorso e schema correnti;
GET innocua con stato HTTP ed esito dello schema, senza token o payload completo;
termine della paginazione, comportamento 429, rinnovo token e durata massima dei retry;
per ogni modifica, idempotenza, approvazione, effetto atteso, verifica e percorso di arresto.

Implementare l’operazione di business solo dopo aver superato questi controlli in un tenant di test o su un record controllato. OAuth2 e routing del tenant restano prerequisiti comuni, non funzionalità Sophos Email.