Kom igång med Sophos Email Management API

Email Management API är det tenantavgränsade automatiseringsgränssnittet för utvalda Sophos Email-uppgifter. Den här introduktionen visar hur API-kontraktet valideras och rätt operationsfamilj väljs. Detaljerade procedurer för skrivning, karantän och clawback hör hemma i respektive runbook; en översikt innebär inget godkännande av ändringar.

Ta över förutsättningarna

Slutför det gemensamma Sophos Fusion API-flödet före det första Email-anropet: autentisera en service principal med OAuth2, identifiera måltenant och hitta dess regionala API-värd. Hantera API-autentiseringsuppgifter för Sophos Fusion (tidigare Sophos Central) säkert beskriver skydd av autentiseringsuppgifter, tokenbegäran, whoami, tenantval för Partner och Enterprise samt gemensam feldiagnostik.

Artikeln tar över exakt tre validerade värden:

• SOPHOS_ACCESS_TOKEN: en kortlivad OAuth2 bearer-token;
• SOPHOS_TENANT_ID: måltenantens UUID;
• SOPHOS_API_HOST: den fullständiga regionala värden för denna tenant.

Den globala värden används bara för identitets- och tenantidentifiering. Email-operationer skickas till den returnerade regionala värden. Härled aldrig region eller tenant från ett visningsnamn. Token, client secret och fullständiga svar får inte hamna i källkod, loggar eller ärenden.

Välj operationsfamilj

Sophos Fusion visar även Message History via XDR-frågor och S/MIME-certifikathantering som Email-API:er. De har separata kontrakt och behörigheter. Överför inte sökvägar, scheman eller antaganden från de fyra familjerna ovan.

Överlämna Message History till XDR Query API

Fortsätt för Message History till den aktuella översikten över XDR Query API. Det är en separat OAuth2-skyddad regional tjänst med /xdr-query/v1 som bas, inte en operation under /email/v1. Bedöm XDR-behörigheter och XDR-fel oberoende av antaganden om Email Management API.

Håll livscykeln begränsad: använd de dokumenterade kategori- och frågedefinitionsoperationerna för att hitta en aktuell frågedefinition, starta en frågekörning med POST, kontrollera körningens status, hämta resultaten när den är klar och avbryt körningen vid behov. Kopiera eller hitta inte på en Email-fråga från den här artikeln. Kontrollera före implementation tillämpliga operations- och svarsscheman för start, status, resultat och avbrott i den länkade aktuella API-beskrivningen.

Öppna den officiella schemavisaren för Email Message History innan en fråga byggs. Välj en tabell i panelen Table name och granska sedan General info, Fields och Custom Types. Som orientering visar det aktuella Email-schemat exakt tre sökbara tabeller: xdr_xge_att_data, xdr_xge_url_data och xdr_xge_events. Livevisaren är fortsatt normerande för fält och typer; artikeln duplicerar avsiktligt ingen fältlista. Dessa Data Lake-tabeller är inte svarsscheman för /email/v1.

Före implementation väljs den exakta operationen i den aktuella API-beskrivningen och HTTP-metod, sökväg, request- och responseschema, behörighet och dokumenterade gränser kontrolleras. Gissa aldrig endpointsökvägar och skapa inte en operation genom att byta ett substantiv.

Lärstigen går från autentisering och tenant-routing till mailboxar, clawback, karantän, post-delivery-karantän och S/MIME.

Bygg requestkontraktet

Den granskade specifikationen använder en regional bas-URL som slutar med /email/v1. Varje tenantanrop kräver bearer-token och X-Tenant-ID; JSON-anrop använder Content-Type: application/json. Lägg endast den dokumenterade produktsökvägen till den validerade värden:

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

Kör ett ofarligt lästest före skrivning i produktion. GET /mailboxes är en listoperation i den granskade specifikationen. pageSize=1 begränsar bara det första svaret och bevisar inte att fler sidor saknas:

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

Testet lyckas när status är 200 och strukturerna items och pages finns. Logga inte svarskroppar ofiltrerat: även en postlådelista innehåller tenantens personuppgifter.

Hantera sidindelning, throttling och tokens livslängd

En lyckad första sida är inte ett fullständigt inventarium. För GET /mailboxes innehåller pages.nextKey nyckeln till nästa sida; skicka den URL-kodad som pageFromKey i nästa begäran. Fortsätt tills ingen nextKey finns, med gränser för antal sidor och körtid samt identifiering av upprepade nycklar. För varje annan operation gäller endast dess aktuellt dokumenterade sidmodell.

Throttling är inget schemafel. Vid 429 följer klienten dokumenterade retry- eller rate-limit-headers, använder begränsad backoff med jitter och begränsar försök och total tid. Upprepa inte skriv-, borttagnings-, frisläppnings- eller clawbackanrop blint: timeout kan inträffa efter att servern accepterat operationen.

Förnya en utgången token via OAuth2. Försök inte kringgå 401 genom att byta tenant eller region. Kontrollera roll, behörighet och tenanttilldelning vid 403; regional värd, dokumenterad sökväg och objekt-ID vid 404. Övriga 4xx behandlas som request- eller tillståndsfel. Begränsa hanteringen av 5xx; fastställ status och möjlig servereffekt före ett kontrollerat nytt försök.

Validera version och produktionssättning

API-specifikationen bakom artikeln granskades som v1.4.0. Kontrollera den aktuella versionen igen före implementation. Sökvägar eller scheman från v1.4.0 är inget löfte för senare versioner.

Dokumentera före produktionssättning:

1. ägare av autentiseringsuppgifter, minsta roll, tenant-ID och identifierad regional värd;
2. vald operationsfamilj samt aktuell metod, sökväg och schema;
3. ofarligt GET-test med HTTP-status och schemaresultat, utan token eller fullständig payload;
4. avslut för sidindelning, beteende vid 429, tokenförnyelse och maximal retrytid;
5. för varje ändring idempotens, godkännande, förväntad effekt, kontroll och stoppväg.

Implementera verksamhetsoperationen först när kontrollerna godkänts i en testtenant eller mot en kontrollerad post. Gemensam OAuth2 och tenantrouting är fortsatt förutsättningar, inte Sophos Email-funktioner i sig.