Sophos Email Postfächer per API automatisieren

Die Sophos Email Management API kann den vollständigen Postfach-Lifecycle abbilden: Bestand suchen, Postfächer einzeln oder gesammelt anlegen, Namen und Beziehungen ändern sowie Objekte löschen. Der sichere Ablauf lautet immer lesen, Soll und Ist vergleichen, gezielt ändern und erneut lesen. Ein erfolgreicher HTTP-Status allein genügt bei Bulk- und Beziehungsoperationen nicht.

Voraussetzungen und Zuständigkeit klären

Dieser Artikel setzt den Einstieg in die Sophos Email Management API voraus. Authentifizierung, Token-Laufzeit, Tenantauflösung und Regionalhost werden im Runbook Sophos Email API authentifizieren und zum Tenant routen behandelt. Für alle folgenden Pfade gelten:

• regionale Basis-URL ${SOPHOS_API_HOST%/}/email/v1;
• Authorization: Bearer <access-token>, X-Tenant-ID: <tenant-uuid> und bei JSON-Bodies Content-Type: application/json;
• eine Postfach-ID als UUID, wo {id} steht;
• die aktuell geprüfte API-Beschreibung. Die hier belegten Schemas stammen aus Email Management API v1.4.0.

Vor dem ersten Schreibzugriff wird festgelegt, welches System den Postfachbestand besitzt. Eine Verzeichnissynchronisierung bleibt die führende Quelle für synchronisierte Objekte. API-Änderungen ersetzen diese Zuständigkeit nicht und können überschrieben oder als Konflikt abgelehnt werden. Die Spezifikation nennt 409 ausdrücklich für ein verzeichnissynchronisiertes Postfach bei Umbenennen, Einzel-Löschen sowie Alias- und Delegiertenänderungen. In diesem Fall wird die Änderung an der Verzeichnisquelle vorgenommen – nicht mit Varianten oder Wiederholungen gegen die API erzwungen.

Bestand vollständig inventarisieren und suchen

GET /mailboxes liefert items sowie das Objekt pages mit fromKey, nextKey, size und maxSize. pageSize unterstützt höchstens 50 Datensätze. Für die nächste Seite wird pages.nextKey URL-kodiert als pageFromKey übergeben; erst ein fehlender nextKey beendet das Inventar. Wiederholte Schlüssel, Seitenzahl und Gesamtlaufzeit begrenzen, damit ein fehlerhafter Lauf nicht endlos weiterarbeitet.

Pro Suchanfrage darf nur ein Suchparameter verwendet werden. Unterstützt sind name, nameStartsWith, email, emailStartsWith, createdAfter, createdBefore, type, bulkSenderPrivilegeStatus, blocked, distributionListOwnedBy, alias, aliasesStartWith und delegate. Die Typen sind user, distributionList, publicFolder und sharedMailbox; der Privilegstatus ist neverRequested, approvalPending, approved, rejected oder revoked. Exakte Filter und Präfixfilter nicht vermischen.

Ein Inventarlauf speichert mindestens id, type, email, name, createdAt und blocked. Je nach Objekt können zusätzlich aliases, delegates, distributionListOwners, bulkSenderPrivilege und policies vorhanden sein. Das vollständige Inventar enthält personenbezogene Daten und gehört nicht ungefiltert in Logs.

Postfächer anlegen, lesen und umbenennen

Die Operationen und Schema-Grenzen sind:

Beim Anlegen hat email das Format E-Mail und 4–320 Zeichen; name umfasst 1–256 Zeichen. type nimmt einen der vier oben genannten Werte an. Eine Einzelanlage antwortet mit 201; 409 bedeutet, dass bereits ein Postfach oder Alias mit dieser E-Mail-Adresse existiert. Nicht mit einer abgewandelten Adresse ausweichen: zuerst das vorhandene Objekt suchen und die Zuständigkeit klären.

Auch die Bulk-Anlage antwortet mit 201, obwohl nur einige Elemente angelegt worden sein können. Deshalb die zurückgegebenen items und errors gegen jede angeforderte E-Mail-Adresse abgleichen, erfolgreiche UUIDs sichern und ausschliesslich eindeutig fehlgeschlagene Elemente korrigieren. Danach jedes erstellte Objekt mit GET /mailboxes/{id} auf type, email und name prüfen. Beim Umbenennen bedeutet 201 „aktualisiert“; der anschliessende GET muss den erwarteten name zeigen.

Aliase, Delegierte und Verteilerlisten-Owner ändern

Alle drei Beziehungen verwenden einen JSON-Body mit den Arrays add und remove. Beide Richtungen können in einem Auftrag stehen; ein leerer oder bereits erfüllter Delta-Schritt sollte vorher durch den GET vermieden werden.

Die Owner-Operation gilt für ein Postfach vom Typ distributionList. Eine 200-Antwort kann bei allen drei Operationen Teilerfolg bedeuten. Daher added und removed sowie errors.failedToAdd und errors.failedToRemove vollständig auswerten. Danach GET /mailboxes/{id} ausführen und den exakten Delta in aliases, delegates oder distributionListOwners prüfen. Nur fehlgeschlagene Werte mit behobener Ursache erneut senden; niemals den kompletten ursprünglichen Auftrag blind wiederholen.

Typische Fehler sind ein bereits verwendeter Alias, ein nicht vorhandener Alias oder ein Delegierter, für dessen Adresse kein Postfach existiert. Ein 400 weist auf Request oder Schema, 404 auf Postfach-ID oder Tenantkontext und 409 bei den dafür dokumentierten Operationen auf Synchronisationsbesitz hin.

Bulk-Sender-Privileg beantragen

POST /mailboxes/{id}/bulksender-privilege-request erwartet zwingend count als Integer, period mit daily, weekly oder monthly und purpose mit 2–2048 Zeichen. Der Zweck sollte den realen Versandfall beschreiben; die API-Beschreibung nennt für count keine numerische Obergrenze, daher keine eigene erfinden.

Die 200-Antwort enthält accepted. accepted: true bestätigt die Annahme des Antrags, nicht dessen Genehmigung. Den weiteren Zustand per GET /mailboxes/{id} in bulkSenderPrivilege.bulkSenderPrivilegeStatus verfolgen. Ein Folgeantrag wird erst nach Prüfung des aktuellen Zustands und der fachlichen Ursache gestellt.

Einzeln und gesammelt sicher löschen

Einzel-Löschen verwendet DELETE /mailboxes/{id}. Die 200-Antwort enthält deleted; dieselbe Antwortklasse ist auch dokumentiert, wenn das Postfach nicht gefunden wird. Der Boolean und ein anschliessender Lesetest sind deshalb wichtiger als der Status allein.

POST /mailboxes/delete löscht bis zu 20 UUIDs im Pflichtarray items. Seine 200-Antwort trennt erfolgreiche items von errors, jeweils über id. Vor beiden Varianten exportiert man die Ziel-UUIDs samt E-Mail-Adresse und gleicht sie unmittelbar vor dem Löschen nochmals gegen ein frisches Inventar ab. Verzeichnissynchronisierte Objekte werden an der Quelle entfernt.

Nicht blind wiederholen: Bei Timeout oder unerwartetem Fehler können laut Sophos bereits einige oder alle angeforderten Postfächer gelöscht worden sein. Danach jede UUID mit GET /mailboxes/{id} oder in Sophos Fusion (ehemals Sophos Central) prüfen, Erfolg und Fehler je Element neu bilden und nur nach erneuter Freigabe die nachweislich noch vorhandenen Ziele senden.

Limits, Fehler und Betriebsabnahme

Sophos dokumentiert täglich 10'000 Requests für Create, Update und Delete sowie 20'000 für Get; das stündliche Limit ist laut Guide jeweils gleich dem täglichen. Alias-, Delegierten-, Owner- und Namensänderungen zählen zu Update. Bei 429 wird der Lauf begrenzt pausiert; er erhöht nicht automatisch Parallelität oder wiederholt verändernde Requests. Für höhere Quoten ist Sophos Support zuständig.

Vor der Produktionsfreigabe sollten folgende Gates bestanden sein:

1. Vollständige Pagination und genau ein Suchfilter pro Request sind getestet.
2. Typ-, E-Mail-, Namens- und Array-Grenzen werden vor dem Senden validiert.
3. Bulk-Antworten und Beziehungsantworten werden pro Element abgeglichen; Teilerfolg gilt nicht als Gesamterfolg.
4. Jeder Schreibzugriff endet mit GET /mailboxes/{id} oder einem gleichwertigen Inventarabgleich.
5. 400, 404, 409, 429 und 5xx werden getrennt behandelt; Requestfehler, fehlende Objekte, Synchronisationsbesitz, Drosselung und Serverfehler werden nicht vermischt.
6. Delete- und andere nicht sicher idempotente Requests werden nach unklarem Ausgang nicht automatisch wiederholt.

Damit bleibt die API Automatisierungswerkzeug und wird nicht versehentlich zur zweiten, konkurrierenden Quelle für den Postfachbestand.