Einstieg in die Sophos Email Management API

Die Email Management API ist die tenantbezogene Automatisierungsschnittstelle für ausgewählte Sophos-Email-Aufgaben. Dieser Einstieg zeigt, wie man den API-Vertrag prüft und die passende Operationsfamilie auswählt. Die detaillierten Schreib-, Quarantäne- und Clawback-Abläufe bleiben in ihren jeweiligen Runbooks; ein Übersichtsartikel ist keine Freigabe für Änderungen.

Voraussetzungen übernehmen

Vor dem ersten Email-Aufruf muss der gemeinsame Sophos-Fusion-API-Ablauf abgeschlossen sein: Service Principal per OAuth2 authentifizieren, Ziel-Tenant bestimmen und dessen regionalen API-Host ermitteln. Sophos Fusion (früher Sophos Central): API-Zugangsdaten sicher verwalten beschreibt Credential-Schutz, Token-Anforderung, whoami, Partner- und Enterprise-Tenantauflösung sowie die gemeinsame Fehlerdiagnose.

Dieser Artikel übernimmt daraus genau drei validierte Werte:

SOPHOS_ACCESS_TOKEN: kurzlebiger OAuth2-Bearer-Token;
SOPHOS_TENANT_ID: UUID des Ziel-Tenants;
SOPHOS_API_HOST: vollständiger regionaler Host für diesen Tenant.

Der globale Host dient nur der Identitäts- und Tenant-Ermittlung. Email-Operationen gehen an den zurückgegebenen regionalen Host. Region oder Tenant niemals aus einem Anzeigenamen ableiten. Token, Client Secret und vollständige Antwortdaten gehören weder in Quellcode noch in Logs oder Tickets.

Operationsfamilie auswählen

Ziel	Familie	Zuerst klären
Postfächer inventarisieren oder verwalten	Mailbox Management	Quelle der Postfachdaten, erlaubte Postfachtypen und ob eine Verzeichnissynchronisierung Owner ist
Vor Zustellung zurückgehaltene Nachrichten untersuchen oder bearbeiten	Quarantine	Filter, Nachrichtenauswahl, Berechtigung und Auswirkung von Freigabe, Löschung oder Anhangsaktion
Bereits zugestellte Nachrichten untersuchen oder bearbeiten	Post-Delivery Quarantine	aktivierter Post-Delivery-Schutz, aktueller Zustand und mögliche asynchrone Jobs
Eine zugestellte Nachricht zurückziehen und Ergebnis verfolgen	Clawback	geeignete Message-ID, Empfängerumfang, Berechtigung und asynchroner Status

Sophos Fusion führt zusätzlich Message History über XDR-Abfragen und S/MIME-Zertifikatsverwaltung als Email-APIs. Dafür gelten eigene Verträge und Berechtigungen. Pfade, Schemas oder Annahmen aus den vier Familien oben werden nicht darauf übertragen.

Message History an die XDR Query API übergeben

Für Message History führt der Einstieg zur aktuellen Übersicht der XDR Query API. Sie ist ein separater, mit OAuth2 geschützter regionaler Dienst unter /xdr-query/v1 und keine Operation unter /email/v1. Deshalb werden XDR-Berechtigungen und XDR-Fehler unabhängig von Annahmen zur Email Management API geprüft.

Der begrenzte Ablauf lautet: Über die dokumentierten Kategorie- und Query-Definition-Operationen eine aktuelle Query-Definition ermitteln, einen Query-Lauf per POST starten, den Laufstatus abfragen, nach Abschluss die Ergebnisse abrufen und den Lauf bei Bedarf abbrechen. Dabei wird keine Email-Query aus diesem Artikel übernommen oder erfunden. Vor der Implementierung sind in der verlinkten aktuellen API-Beschreibung die jeweiligen Operations- und Antwortschemas für Start, Status, Ergebnisse und Abbruch zu prüfen.

Vor dem Aufbau einer Query den offiziellen Email-Message-History-Schema-Viewer öffnen. Im Bereich Table name eine Tabelle auswählen und zuerst General info, Fields und Custom Types prüfen. Zur Orientierung enthält das aktuelle Email-Schema genau die drei auffindbaren Tabellen xdr_xge_att_data, xdr_xge_url_data und xdr_xge_events. Für Felder und Typen bleibt jedoch der Live-Viewer verbindlich; dieser Artikel dupliziert keine Feldliste. Diese Data-Lake-Tabellen sind keine Antwortschemas von /email/v1.

Vor jeder Implementierung wird in der aktuellen API-Beschreibung die konkrete Operation samt HTTP-Methode, Pfad, Request-Schema, Antwortschema, Berechtigung und dokumentierten Limits ausgewählt. Endpunktpfade nicht erraten und keine Operation durch Austausch eines Substantivs ableiten.

Der Lernpfad führt vom Authentifizierungs- und Tenant-Routing-Runbook weiter zu Postfächern, Clawback, Quarantäne, Post-Delivery Quarantine und S/MIME.

Request-Vertrag bilden

Die geprüfte Spezifikation verwendet eine regionale Basis-URL mit /email/v1. Jeder tenantbezogene Request benötigt den Bearer-Token und X-Tenant-ID; JSON-Aufrufe verwenden Content-Type: application/json. Den bereits validierten Host nur um den dokumentierten Produktpfad ergänzen:

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

Vor produktiven Schreiboperationen einen ungefährlichen Lesetest ausführen. GET /mailboxes ist in der geprüften Spezifikation eine Listenoperation; pageSize=1 begrenzt nur die erste Antwort und beweist nicht, dass es keine weiteren Seiten gibt:

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

Der Test ist erfolgreich, wenn Status 200 und die erwarteten items- und pages-Strukturen vorhanden sind. Antwortinhalte nicht ungefiltert protokollieren: Schon eine Postfachliste enthält personenbezogene Tenant-Daten.

Pagination, Drosselung und Token-Laufzeit berücksichtigen

Eine erfolgreiche erste Seite ist kein vollständiges Inventar. Bei GET /mailboxes enthält pages.nextKey den Schlüssel für die nächste Seite; dieser wird bei der nächsten Anfrage als pageFromKey URL-kodiert übergeben. Der Client läuft bis kein nextKey mehr vorhanden ist, begrenzt Seiten und Laufzeit und erkennt wiederholte Schlüssel. Für jede andere Operation gilt ausschliesslich deren aktuell dokumentiertes Pagination-Modell.

Drosselung ist kein Schemafehler. Bei 429 beachtet der Client dokumentierte Retry- oder Rate-Limit-Header, wartet mit begrenztem Backoff und Jitter und setzt eine Obergrenze für Versuche und Gesamtdauer. Schreib-, Lösch-, Freigabe- und Clawback-Aufrufe werden nicht blind wiederholt, weil eine Zeitüberschreitung nach serverseitiger Annahme eintreten kann.

Ein abgelaufener Token wird über den OAuth2-Ablauf erneuert. Ein 401 wird nicht durch Ändern von Tenant oder Region umgangen. Bei 403 werden Rolle, Berechtigung und Tenantzuordnung geprüft; bei 404 zuerst Regionalhost, dokumentierter Pfad und Objekt-ID. Andere 4xx-Antworten werden als Request- oder Zustandsfehler behandelt. Bei 5xx bleibt der Auftrag begrenzt; erst Status und mögliche serverseitige Wirkung klären, dann kontrolliert erneut versuchen.

Version und Produktionsfreigabe abnehmen

Die diesem Artikel zugrunde liegende API-Spezifikation wurde als v1.4.0 geprüft. Vor der Implementierung muss die aktuelle Version erneut geprüft werden. Der Pfadbestand oder ein Schema aus v1.4.0 ist keine Zusage für spätere Versionen.

Vor der Freigabe dokumentieren:

Credential-Owner, minimale Rolle, Tenant-ID und ermittelten Regionalhost;
ausgewählte Operationsfamilie sowie aktuelle Methode, Pfad und Schema;
ungefährlichen GET-Test mit HTTP-Status und Schemaergebnis, aber ohne Token oder vollständige Nutzdaten;
Pagination-Abbruch, 429-Verhalten, Token-Erneuerung und maximale Retry-Dauer;
für jede Änderung Idempotenz, Freigabe, erwartete Wirkung, Nachkontrolle und Abbruchweg.

Erst wenn diese Punkte für einen Test-Tenant oder einen kontrollierten Datensatz abgenommen sind, wird die konkrete Fachoperation implementiert. Die gemeinsame OAuth2- und Tenant-Routing-Mechanik bleibt Voraussetzung und ist selbst keine Sophos-Email-Funktion.