Automate Sophos Email mailboxes with the API

The Sophos Email Management API can cover the complete mailbox lifecycle: search the inventory, create mailboxes individually or in batches, change names and relationships, and delete objects. The safe sequence is always read, compare desired and actual state, make a targeted change, and read again. An HTTP success status alone is not sufficient for bulk and relationship operations.

Confirm prerequisites and ownership

This article assumes the Sophos Email Management API introduction. Authentication, token lifetime, tenant resolution and regional host selection are covered in Authenticate the Sophos Email API and route to the tenant. All paths below require:

• the regional base URL ${SOPHOS_API_HOST%/}/email/v1;
• Authorization: Bearer <access-token>, X-Tenant-ID: <tenant-uuid>, and Content-Type: application/json for JSON bodies;
• a mailbox UUID wherever {id} appears;
• the currently published API contract. The schemas verified here are from Email Management API v1.4.0.

Before the first write, decide which system owns the mailbox inventory. Directory synchronization remains authoritative for synchronized objects. API changes do not replace that ownership and may be overwritten or rejected as conflicts. The specification explicitly documents 409 for a directory-synchronized mailbox when renaming, deleting one mailbox, and changing aliases or delegates. Make that change at the directory source rather than forcing API variants or retries.

Inventory and search every mailbox

GET /mailboxes returns items and a pages object containing fromKey, nextKey, size, and maxSize. pageSize supports at most 50 records. URL-encode pages.nextKey as pageFromKey for the next request; the inventory is complete only when nextKey is absent. Cap repeated keys, page count, and total runtime so a faulty run cannot continue forever.

Only one search parameter may be used per request. Supported parameters are name, nameStartsWith, email, emailStartsWith, createdAfter, createdBefore, type, bulkSenderPrivilegeStatus, blocked, distributionListOwnedBy, alias, aliasesStartWith, and delegate. Types are user, distributionList, publicFolder, and sharedMailbox; privilege status is neverRequested, approvalPending, approved, rejected, or revoked. Do not combine exact and prefix filters.

At minimum, retain id, type, email, name, createdAt, and blocked. Depending on the object, aliases, delegates, distributionListOwners, bulkSenderPrivilege, and policies may also be present. The complete inventory contains personal data and must not be written to logs without filtering.

Create, read, and rename mailboxes

The operations and schema limits are:

For creation, email uses email format and 4–320 characters; name uses 1–256 characters. type accepts one of the four values above. Single creation returns 201; 409 means a mailbox or alias already uses that email address. Do not work around this with an altered address: locate the existing object and resolve ownership first.

Bulk creation also returns 201 when only some elements were created. Reconcile returned items and errors against every requested email address, retain successful UUIDs, and correct only clearly failed elements. Then verify every created object with GET /mailboxes/{id} against type, email, and name. A rename returns 201; the following GET must show the expected name.

Change aliases, delegates, and distribution-list owners

All three relationships use a JSON body with add and remove arrays. Both directions can be included in one request; avoid an empty or already satisfied delta by reading first.

The owner operation applies to a mailbox of type distributionList. For all three operations, a 200 response can represent partial success. Evaluate added and removed plus errors.failedToAdd and errors.failedToRemove in full. Then call GET /mailboxes/{id} and verify the exact delta in aliases, delegates, or distributionListOwners. Retry only failed values after fixing their cause; never replay the complete original request blindly.

Typical failures include an alias already in use, an alias that does not exist, or a delegate whose address has no mailbox. A 400 points to the request or schema, 404 to mailbox ID or tenant context, and 409 on operations that document it to synchronization ownership.

Request bulk-sender privilege

POST /mailboxes/{id}/bulksender-privilege-request requires integer count, period set to daily, weekly, or monthly, and purpose of 2–2048 characters. Describe the real sending use case in the purpose. The API contract specifies no numeric upper bound for count, so do not invent one.

The 200 response contains accepted. accepted: true confirms submission, not approval. Track the later state with GET /mailboxes/{id} at bulkSenderPrivilege.bulkSenderPrivilegeStatus. Submit another request only after checking the current state and the business cause.

Delete individually and in bulk without blind retries

Single deletion uses DELETE /mailboxes/{id}. Its 200 response contains deleted; the same response class is also documented when the mailbox cannot be found. The Boolean and a subsequent read check therefore matter more than status alone.

POST /mailboxes/delete deletes up to 20 UUIDs in the required items array. Its 200 response separates successful items from errors, keyed by id. Before either deletion, export target UUIDs with their email addresses and reconcile them against a fresh inventory immediately before execution. Remove directory-synchronized objects at their source.

Never retry blindly: Sophos warns that a timeout or unexpected error may occur after some or all requested mailboxes have already been deleted. Check every UUID with GET /mailboxes/{id} or in Sophos Fusion (formerly Sophos Central), rebuild success and failure sets per item, and resend only targets proven to remain after renewed approval.

Accept limits, errors, and production gates

Sophos documents 10,000 requests per day for Create, Update, and Delete, and 20,000 for Get; the guide says the hourly limit is the same as the daily limit. Alias, delegate, owner, and name changes count as Update. On 429, pause the run within defined bounds; do not automatically add concurrency or replay mutating requests. Contact Sophos Support for a higher quota.

Before production, pass these gates:

1. Complete pagination and exactly one search filter per request have been tested.
2. Type, email, name, and array limits are validated before submission.
3. Bulk and relationship responses are reconciled per element; partial success is not treated as total success.
4. Every write ends with GET /mailboxes/{id} or an equivalent inventory reconciliation.
5. Handle 400, 404, 409, 429, and 5xx separately; do not confuse request errors, missing objects, synchronization ownership, throttling, and server errors.
6. Delete and other operations that are not safely idempotent are not automatically retried after an uncertain outcome.

This keeps the API an automation tool rather than an accidental second, competing source of mailbox truth.