Automatisera Sophos Email-postlådor via API
Sophos Email Management API täcker hela postlådans livscykel: sök i inventariet, skapa enskilt eller i bulk, ändra namn och relationer samt radera objekt. Den säkra ordningen är alltid läs, jämför önskat och faktiskt tillstånd, gör en riktad ändring och läs igen. En lyckad HTTP-status räcker inte för bulk- och relationsåtgärder.
Bekräfta förutsättningar och ägarskap
Artikeln förutsätter introduktionen till Sophos Email Management API. Autentisering, tokenlivslängd, tenantupplösning och regional värd beskrivs i Autentisera Sophos Email API och dirigera till tenant. Alla sökvägar kräver regional bas-URL ${SOPHOS_API_HOST%/}/email/v1, Authorization: Bearer <access-token>, X-Tenant-ID: <tenant-uuid>, för JSON Content-Type: application/json, och UUID där {id} står. Scheman här är verifierade mot Email Management API v1.4.0; kontrollera alltid aktuellt kontrakt.
Bestäm före skrivning vilket system som äger inventariet. Katalogsynkronisering är fortsatt auktoritativ för synkroniserade objekt. API:t ersätter inte ägarskapet; ändringar kan skrivas över eller nekas. Specifikationen dokumenterar 409 vid namnbyte, enskild radering samt ändring av alias eller delegater för en synkroniserad postlåda. Ändra katalogkällan i stället för att tvinga varianter eller retries via API:t.
Inventera och sök alla postlådor
GET /mailboxes returnerar items och pages med fromKey, nextKey, size, maxSize. pageSize stöder högst 50 poster. URL-koda pages.nextKey som nästa pageFromKey; inventariet är komplett först när nextKey saknas. Begränsa upprepade nycklar, sidantal och total körtid.
Endast en sökparameter får användas per anrop: name, nameStartsWith, email, emailStartsWith, createdAfter, createdBefore, type, bulkSenderPrivilegeStatus, blocked, distributionListOwnedBy, alias, aliasesStartWith eller delegate. Typer är user, distributionList, publicFolder, sharedMailbox; statusar är neverRequested, approvalPending, approved, rejected, revoked. Blanda inte exakta filter och prefixfilter.
Spara minst id, type, email, name, createdAt, blocked. Även aliases, delegates, distributionListOwners, bulkSenderPrivilege, policies kan finnas. Logga inte personuppgifterna ofiltrerat.
Skapa, läs och byt namn på postlådor
| Uppgift | Metod och sökväg | Kontrakt |
|---|---|---|
| Skapa en | POST /mailboxes | type, email, name krävs |
| Skapa högst 10 | POST /mailboxes/bulk | obligatorisk items, högst 10 |
| Läs en | GET /mailboxes/{id} | UUID id, aktuellt tillstånd |
| Ändra namn | PATCH /mailboxes/{id} | name, 1–256 tecken |
Vid skapande har email e-postformat och 4–320 tecken, name 1–256; type accepterar de fyra värdena. Enskilt skapande ger 201; 409 betyder att en postlåda eller ett alias redan använder adressen. Leta upp objektet och lös ägarskapet i stället för att kringgå med en ändrad adress.
Bulkskapande ger också 201 vid delvis framgång. Stäm av items och errors mot varje begärd adress, spara lyckade UUID:n och korrigera endast misslyckade element. Verifiera varje objekt med GET /mailboxes/{id} mot type, email, name. Efter namnbyte ska 201 följas av GET med förväntat name.
Ändra alias, delegater och distributionslistägare
Relationerna använder JSON-arrayerna add och remove, även tillsammans. Läs först för att undvika en tom eller redan uppfylld delta.
| Relation | Sökväg | Maximum per add och remove |
|---|---|---|
| Alias | POST /mailboxes/{id}/aliases | 100 |
| Delegater | POST /mailboxes/{id}/delegates | 50 |
| Distributionslistägare | POST /mailboxes/{id}/distribution-list-owners | 1 |
Den sista gäller typen distributionList. 200 kan betyda delvis framgång. Utvärdera added, removed, errors.failedToAdd, errors.failedToRemove och verifiera sedan exakt delta via GET i aliases, delegates eller distributionListOwners. Försök endast om misslyckade värden efter att orsaken åtgärdats, aldrig hela anropet blint. Vanliga fel är upptaget eller saknat alias och delegat utan postlåda. 400 avser anrop/schema, 404 ID/tenantkontext och dokumenterad 409 synkroniseringsägarskap.
Ansök om massutskicksbehörighet
POST /mailboxes/{id}/bulksender-privilege-request kräver heltalsfältet count, period som daily, weekly eller monthly, och purpose med 2–2048 tecken. Beskriv verklig användning. Kontraktet anger ingen numerisk övre gräns för count; hitta inte på en. 200 innehåller accepted; accepted: true bekräftar inskickning, inte godkännande. Följ bulkSenderPrivilege.bulkSenderPrivilegeStatus via GET och skicka ny ansökan först efter kontroll av status och verksamhetsorsak.
Radera utan blinda retries
Enskild radering använder DELETE /mailboxes/{id}. 200 innehåller deleted; samma svarsklass dokumenteras även när postlådan inte hittas. Kontrollera både boolean och tillståndet efteråt.
POST /mailboxes/delete raderar högst 20 UUID:n i obligatoriska items; 200 delar upp lyckade items och errors per id. Exportera först UUID med adress och jämför mot färskt inventarium. Radera synkroniserade objekt vid källan.
Försök aldrig blint igen: efter timeout eller oväntat fel kan några eller alla postlådor redan vara raderade. Kontrollera varje UUID via GET eller Sophos Fusion (tidigare Sophos Central), bygg om resultat per element och skicka efter nytt godkännande bara mål som bevisligen finns kvar.
Gränser, fel och produktionskontroll
Sophos dokumenterar 10 000 anrop per dag för Create, Update och Delete samt 20 000 för Get; guiden säger att timgränsen är samma som dygnsgränsen. Namn-, alias-, delegat- och ägarändringar räknas som Update. Pausa begränsat vid 429; öka inte samtidighet och upprepa inte mutationer automatiskt. Kontakta Sophos Support för större kvot.
Testa före produktion: full paginering och ett filter per anrop; typ-, e-post-, namn- och arraygränser före sändning; avstämning per element för bulk och relationer; GET eller inventarieavstämning efter varje skrivning; separat hantering av 400, 404, 409, 429, 5xx; inga automatiska retries av Delete eller andra icke-idempotenta åtgärder efter osäkert resultat. Då förblir API:t ett automationsverktyg, inte en konkurrerande sanningskälla.