Aan de slag met de Sophos Email Management API

De Email Management API is de tenantgebonden automatiseringsinterface voor geselecteerde Sophos Email-taken. Deze introductie legt uit hoe je het API-contract valideert en de juiste bewerkingsfamilie kiest. Gedetailleerde schrijf-, quarantaine- en clawbackprocedures horen in hun eigen runbooks; een overzicht geeft geen toestemming voor wijzigingen.

Vereisten overnemen

Voltooi vóór het eerste Email-verzoek de gedeelde Sophos Fusion API-procedure: authenticeer een service principal met OAuth2, identificeer de doeltenant en ontdek de regionale API-host. Sophos Fusion-API-referenties (voorheen Sophos Central) veilig beheren behandelt bescherming van referenties, tokenaanvraag, whoami, tenantselectie voor Partner en Enterprise en gedeelde foutdiagnose.

Dit artikel neemt exact drie gevalideerde waarden over:

• SOPHOS_ACCESS_TOKEN: een kortlevend OAuth2-bearertoken;
• SOPHOS_TENANT_ID: de UUID van de doeltenant;
• SOPHOS_API_HOST: de volledige regionale host van die tenant.

De globale host dient uitsluitend voor identificatie en tenantdetectie. Stuur Email-bewerkingen naar de teruggegeven regionale host. Leid regio of tenant nooit af uit een weergavenaam. Tokens, client secrets en volledige antwoorden horen niet in broncode, logs of tickets.

De bewerkingsfamilie kiezen

Sophos Fusion toont ook Message History via XDR-query’s en S/MIME-certificaatbeheer als Email-API’s. Hiervoor gelden afzonderlijke contracten en rechten. Neem paden, schema’s of aannames van de vier families hierboven niet over.

Message History overdragen aan de XDR Query API

Ga voor Message History verder naar het actuele overzicht van de XDR Query API. Dit is een afzonderlijke, met OAuth2 beveiligde regionale service met /xdr-query/v1 als basis, geen bewerking onder /email/v1. Beoordeel XDR-rechten en XDR-fouten los van aannames over de Email Management API.

Houd de levenscyclus begrensd: gebruik de gedocumenteerde categorie- en querydefinitiebewerkingen om een actuele querydefinitie te vinden, start een queryrun met POST, controleer de runstatus, haal de resultaten op zodra de run voltooid is en annuleer de run wanneer dat nodig is. Neem geen Email-query uit dit artikel over en verzin er geen. Controleer vóór implementatie in de gekoppelde actuele API-beschrijving de toepasselijke bewerkings- en responseschema’s voor starten, controleren, resultaten ophalen en annuleren.

Open vóór het opbouwen van een query de officiële schemaviewer voor Email Message History. Selecteer een tabel in het deelvenster Table name en bekijk daarna General info, Fields en Custom Types. Ter oriëntatie toont het actuele Email-schema exact drie vindbare tabellen: xdr_xge_att_data, xdr_xge_url_data en xdr_xge_events. De liveviewer blijft leidend voor velden en typen; dit artikel dupliceert bewust geen veldenlijst. Deze Data Lake-tabellen zijn geen responseschema’s van /email/v1.

Kies vóór implementatie de exacte bewerking in de actuele API-beschrijving en controleer HTTP-methode, pad, request- en responseschema, rechten en gedocumenteerde limieten. Raad nooit endpointpaden en leid geen bewerking af door een zelfstandig naamwoord te vervangen.

Het leerpad loopt van authenticatie en tenant-routing naar mailboxes, clawback, quarantaine, post-deliveryquarantaine en S/MIME.

Het requestcontract opbouwen

De beoordeelde specificatie gebruikt een regionale basis-URL die eindigt op /email/v1. Elk tenantgebonden verzoek vereist het bearertoken en X-Tenant-ID; JSON-aanroepen gebruiken Content-Type: application/json. Voeg aan de gevalideerde host alleen het gedocumenteerde productpad toe:

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

Voer vóór schrijfacties in productie een onschuldige leestest uit. GET /mailboxes is in de beoordeelde specificatie een lijstbewerking. pageSize=1 beperkt alleen het eerste antwoord en bewijst niet dat er geen volgende pagina is:

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

De test slaagt bij status 200 en aanwezige items- en pages-structuren. Log antwoorden niet ongefilterd: zelfs een mailboxlijst bevat persoonsgegevens van de tenant.

Rekening houden met paginering, throttling en tokenlevensduur

Een geslaagde eerste pagina is geen volledige inventaris. Bij GET /mailboxes bevat pages.nextKey de sleutel voor de volgende pagina; geef die URL-gecodeerd als pageFromKey mee in het volgende verzoek. Ga door tot geen nextKey resteert, met grenzen voor pagina’s en looptijd en detectie van herhaalde sleutels. Voor iedere andere bewerking geldt uitsluitend het actueel gedocumenteerde pagineringsmodel.

Throttling is geen schemafout. Respecteer bij 429 de gedocumenteerde retry- of rate-limitheaders, gebruik begrensde backoff met jitter en begrens pogingen en totale duur. Herhaal schrijf-, verwijder-, vrijgave- of clawbackaanroepen niet blind: een timeout kan optreden nadat de server de bewerking heeft geaccepteerd.

Vernieuw een verlopen token via OAuth2. Omzeil 401 niet door tenant of regio te wijzigen. Controleer bij 403 rol, recht en tenanttoewijzing; bij 404 regionale host, gedocumenteerd pad en object-ID. Behandel overige 4xx als request- of statusfouten. Houd 5xx-afhandeling begrensd en bepaal status en mogelijk servereffect vóór een gecontroleerde nieuwe poging.

Versie en productie-ingebruikname valideren

De API-specificatie waarop dit artikel is gebaseerd, is beoordeeld als v1.4.0. Controleer vóór implementatie opnieuw de actuele versie. Paden of schema’s uit v1.4.0 zijn geen toezegging voor latere versies.

Leg vóór ingebruikname vast:

1. eigenaar van de referenties, minimale rol, tenant-ID en ontdekte regionale host;
2. gekozen bewerkingsfamilie en actuele methode, pad en schema;
3. onschuldige GET-test met HTTP-status en schemaresultaat, zonder token of volledige payload;
4. einde van paginering, gedrag bij 429, tokenvernieuwing en maximale retryduur;
5. voor elke mutatie idempotentie, goedkeuring, verwacht effect, nacontrole en stopprocedure.

Implementeer de zakelijke bewerking pas nadat deze controles slagen in een testtenant of op een gecontroleerd record. Gedeelde OAuth2- en tenantrouting blijven vereisten; het zijn zelf geen Sophos Email-functies.