Sophos Email-mailboxen automatiseren via de API

De Sophos Email Management API ondersteunt de hele mailboxcyclus: de inventaris doorzoeken, mailboxen afzonderlijk of in bulk maken, namen en relaties wijzigen en objecten verwijderen. De veilige volgorde is altijd lezen, gewenste en werkelijke toestand vergelijken, gericht wijzigen en opnieuw lezen. Alleen een succesvolle HTTP-status is bij bulk- en relatiebewerkingen niet voldoende.

Vereisten en eigenaarschap bevestigen

Dit artikel veronderstelt de introductie tot de Sophos Email Management API. Authenticatie, tokenlevensduur, tenantbepaling en regionale host staan in Sophos Email API authenticeren en naar de tenant routeren. Alle onderstaande paden vereisen de regionale basis-URL ${SOPHOS_API_HOST%/}/email/v1, Authorization: Bearer <access-token>, X-Tenant-ID: <tenant-uuid>, bij JSON Content-Type: application/json, en een mailbox-UUID voor {id}. De hier geverifieerde schema’s komen uit Email Management API v1.4.0; controleer steeds het actuele contract.

Bepaal vóór schrijven welk systeem de inventaris bezit. Directorysynchronisatie blijft leidend voor gesynchroniseerde objecten; API-wijzigingen vervangen dat eigenaarschap niet en kunnen worden overschreven of geweigerd. De specificatie documenteert 409 bij hernoemen, afzonderlijk verwijderen en wijzigen van aliassen of gedelegeerden van een gesynchroniseerde mailbox. Wijzig dan de directorybron en forceer geen API-varianten of retries.

Alle mailboxen inventariseren en zoeken

GET /mailboxes retourneert items en pages met fromKey, nextKey, size en maxSize. pageSize ondersteunt maximaal 50 records. URL-encodeer pages.nextKey als de volgende pageFromKey; pas zonder nextKey is de inventaris compleet. Begrens herhaalde sleutels, pagina’s en totale looptijd.

Per request is slechts één zoekparameter toegestaan: name, nameStartsWith, email, emailStartsWith, createdAfter, createdBefore, type, bulkSenderPrivilegeStatus, blocked, distributionListOwnedBy, alias, aliasesStartWith of delegate. Typen zijn user, distributionList, publicFolder, sharedMailbox; statussen zijn neverRequested, approvalPending, approved, rejected, revoked. Combineer exacte en prefixfilters niet.

Bewaar minstens id, type, email, name, createdAt en blocked. Ook aliases, delegates, distributionListOwners, bulkSenderPrivilege en policies kunnen voorkomen. Log deze persoonsgegevens niet ongefilterd.

Mailboxen maken, lezen en hernoemen

Bij maken heeft email e-mailformaat en 4–320 tekens; name 1–256. type gebruikt een van de vier waarden. Enkelvoudig maken retourneert 201; 409 betekent dat een mailbox of alias dit adres al gebruikt. Zoek het bestaande object en los eigenaarschap op in plaats van een gewijzigd adres te gebruiken.

Bulk maken retourneert ook 201 bij gedeeltelijk succes. Vergelijk items en errors met elk aangevraagd adres, bewaar geslaagde UUID’s en herstel alleen aantoonbaar mislukte elementen. Controleer daarna elk object via GET /mailboxes/{id} op type, email en name. Na hernoemen moet de 201-respons gevolgd worden door een GET die de verwachte name toont.

Aliassen, gedelegeerden en lijst-eigenaren wijzigen

Alle relaties gebruiken JSON-arrays add en remove, desgewenst samen. Lees eerst om een lege of al toegepaste delta te vermijden.

De laatste bewerking geldt voor distributionList. 200 kan gedeeltelijk succes betekenen. Verwerk added, removed, errors.failedToAdd en errors.failedToRemove, en controleer per GET de exacte delta in aliases, delegates of distributionListOwners. Herhaal uitsluitend mislukte waarden nadat hun oorzaak is hersteld, nooit blind de hele aanvraag. Veelvoorkomend zijn een bezette of ontbrekende alias en een gedelegeerde zonder mailbox. 400 duidt op request/schema, 404 op ID/tenantcontext en gedocumenteerde 409 op synchronisatie-eigenaarschap.

Bulkafzenderprivilege aanvragen

POST /mailboxes/{id}/bulksender-privilege-request vereist integer count, period als daily, weekly of monthly, en purpose van 2–2048 tekens. Beschrijf het werkelijke gebruik. Het contract geeft geen numerieke bovengrens voor count; verzin er geen. De 200-respons bevat accepted; accepted: true bevestigt indiening, niet goedkeuring. Volg met GET bulkSenderPrivilege.bulkSenderPrivilegeStatus en vraag pas opnieuw aan na controle van status en zakelijke reden.

Verwijderen zonder blinde retries

Afzonderlijk verwijderen gebruikt DELETE /mailboxes/{id}. De 200-respons bevat deleted; dezelfde responsklasse geldt ook als de mailbox niet wordt gevonden. Controleer boolean én de toestand achteraf.

POST /mailboxes/delete verwijdert maximaal 20 UUID’s in de verplichte items-array en splitst in de 200-respons succesvolle items en errors per id. Exporteer vooraf UUID met adres en vergelijk vlak voor uitvoering met een actuele inventaris. Verwijder gesynchroniseerde objecten bij de bron.

Nooit blind opnieuw proberen: na timeout of onverwachte fout kunnen sommige of alle mailboxen al verwijderd zijn. Controleer iedere UUID via GET of Sophos Fusion (voorheen Sophos Central), bouw resultaten per element opnieuw op en verzend na nieuwe goedkeuring alleen bewezen resterende doelen.

Limieten, fouten en productiecontrole

Sophos documenteert dagelijks 10.000 requests voor Create, Update en Delete en 20.000 voor Get; volgens de handleiding is de uurlimiet gelijk aan de daglimiet. Naam-, alias-, gedelegeerde- en eigenaarwijzigingen tellen als Update. Pauzeer bij 429 begrensd; verhoog geen concurrency en herhaal mutaties niet automatisch. Vraag Sophos Support om meer quota.

Test vóór productie: volledige paginering en één filter per request; type-, e-mail-, naam- en arraygrenzen vóór verzending; reconciliatie per element voor bulk en relaties; GET of inventariscontrole na elke write; afzonderlijke behandeling van 400, 404, 409, 429, 5xx; en geen automatische retry van Delete of andere niet veilig idempotente bewerkingen na een onzekere uitkomst. Zo blijft de API een automatiseringstool en geen concurrerende bron van waarheid.