Get started with the Sophos Email Management API

The Email Management API is the tenant-scoped automation interface for selected Sophos Email tasks. This entry point explains how to validate the API contract and choose the appropriate operation family. Detailed write, quarantine, and clawback procedures belong in their respective runbooks; an overview does not authorize a change.

Bring forward the prerequisites

Complete the shared Sophos Fusion API workflow before the first Email request: authenticate a service principal with OAuth2, identify the target tenant, and discover its regional API host. Manage Sophos Fusion (formerly Sophos Central) API credentials securely covers credential protection, token requests, whoami, partner and Enterprise tenant resolution, and shared error diagnosis.

This article consumes exactly three validated values from that workflow:

• SOPHOS_ACCESS_TOKEN: a short-lived OAuth2 bearer token;
• SOPHOS_TENANT_ID: the target tenant’s UUID;
• SOPHOS_API_HOST: the complete regional host for that tenant.

The global host is only for identity and tenant discovery. Send Email operations to the returned regional host. Never infer a region or tenant from a display name. Tokens, client secrets, and complete response payloads must not enter source code, logs, or tickets.

Choose the operation family

Sophos Fusion also presents Message History through XDR queries and S/MIME certificate management as Email APIs. They have separate contracts and permissions. Do not transfer paths, schemas, or assumptions from the four families above to them.

Hand Message History off to the XDR Query API

For Message History, continue to the current XDR Query API overview. This is a separate OAuth2-protected regional service rooted at /xdr-query/v1, not an operation under /email/v1. Evaluate XDR permissions and XDR errors independently of Email Management API assumptions.

Keep the lifecycle bounded: use the documented category and query-definition operations to discover a current query definition, POST a query run, inspect the run status, retrieve its results when complete, and cancel the run when required. Do not copy or invent an Email query from this article. Before implementation, use the linked current API description to review the applicable operation and response schemas for starting, inspecting, retrieving results, and cancelling.

Before constructing a query, open the official Email Message History schema viewer. Select a table in the Table name pane, then inspect General info, Fields, and Custom Types. For orientation, the current Email schema exposes exactly three discoverable tables: xdr_xge_att_data, xdr_xge_url_data, and xdr_xge_events. The live viewer remains authoritative for fields and types; this article deliberately does not duplicate a field list. These Data Lake tables are not /email/v1 response schemas.

Before implementing anything, select the exact operation in the current API description and review its HTTP method, path, request schema, response schema, permission, and documented limits. Never guess endpoint paths or derive an operation by replacing a noun.

The learning path runs from authentication and tenant routing to mailboxes, clawback, quarantine, post-delivery quarantine, and S/MIME.

Build the request contract

The reviewed specification uses a regional base URL ending in /email/v1. Every tenant-scoped request requires the bearer token and X-Tenant-ID; JSON calls use Content-Type: application/json. Append only the documented product path to the already validated host:

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

Run a harmless read test before production writes. GET /mailboxes is a list operation in the reviewed specification. pageSize=1 limits only the first response; it does not prove that there are no additional pages:

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

The test passes when the status is 200 and the expected items and pages structures exist. Do not log response bodies indiscriminately: even a mailbox list contains personal tenant data.

Account for pagination, throttling, and token lifetime

A successful first page is not a complete inventory. For GET /mailboxes, pages.nextKey contains the key for the next page; pass it URL-encoded as pageFromKey on the next request. Continue until no nextKey remains, while bounding page count and runtime and detecting repeated keys. For every other operation, follow only its currently documented pagination model.

Throttling is not a schema error. On 429, honor documented retry or rate-limit headers, use bounded backoff with jitter, and cap attempts and total duration. Do not blindly retry write, delete, release, or clawback calls: a timeout can occur after the server accepted the operation.

Renew an expired token through the OAuth2 workflow. Do not work around 401 by changing tenant or region. For 403, check role, permission, and tenant assignment. For 404, first check the regional host, documented path, and object ID. Treat other 4xx responses as request or state errors. Keep 5xx handling bounded; establish status and possible server-side effect before a controlled retry.

Validate the version and production release

The API specification underlying this article was reviewed at v1.4.0. Verify the current version again before implementation. The path set or a schema from v1.4.0 is not a promise for later versions.

Before release, record:

1. credential owner, minimum role, tenant ID, and discovered regional host;
2. selected operation family and current method, path, and schema;
3. harmless GET test with HTTP status and schema result, but no token or complete payload;
4. pagination termination, 429 behavior, token renewal, and maximum retry duration;
5. for every mutation, idempotency, approval, expected effect, validation, and stop path.

Implement the specific business operation only after these controls pass in a test tenant or against a controlled record. Shared OAuth2 and tenant-routing mechanics remain prerequisites; they are not Sophos Email features themselves.