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 Central 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 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

Central 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.