Introdução à API Sophos Email Management

A Email Management API é a interface de automação limitada ao tenant para determinadas tarefas do Sophos Email. Esta introdução explica como validar o contrato da API e escolher a família de operações adequada. Os procedimentos detalhados de escrita, quarentena e clawback ficam nos respetivos runbooks; uma visão geral não autoriza alterações.

Herdar os pré-requisitos

Antes do primeiro pedido de Email, é necessário concluir o fluxo comum da API Sophos Fusion: autenticar um service principal com OAuth2, identificar o tenant de destino e descobrir o respetivo host regional. Gerir credenciais da API Sophos Fusion (anteriormente Sophos Central) em segurança abrange proteção de credenciais, pedido de token, whoami, resolução de tenants Partner e Enterprise e diagnóstico comum.

Este artigo recebe exatamente três valores validados:

• SOPHOS_ACCESS_TOKEN: token bearer OAuth2 de curta duração;
• SOPHOS_TENANT_ID: UUID do tenant de destino;
• SOPHOS_API_HOST: host regional completo desse tenant.

O host global serve apenas para descobrir identidade e tenant. As operações de Email usam o host regional devolvido. Nunca se deduz a região ou o tenant a partir de um nome visível. Tokens, client secrets e respostas completas não devem entrar em código, logs ou tickets.

Escolher a família de operações

O Sophos Fusion também apresenta o Message History através de consultas XDR e a gestão de certificados S/MIME como APIs de Email. Estas têm contratos e permissões separados. Não se transferem para elas caminhos, esquemas ou pressupostos das quatro famílias acima.

Encaminhar o Message History para a XDR Query API

Para o Message History, deve prosseguir-se para a visão geral atual da XDR Query API. Trata-se de um serviço regional separado, protegido por OAuth2 e baseado em /xdr-query/v1, não de uma operação em /email/v1. As permissões e os erros XDR são avaliados separadamente dos pressupostos da Email Management API.

O ciclo de vida deve permanecer limitado: usar as operações documentadas de categorias e definições de consulta para encontrar uma definição atual, iniciar uma execução com POST, consultar o respetivo estado, obter os resultados quando terminar e cancelar a execução quando necessário. Este artigo não fornece nem inventa uma consulta de Email. Antes da implementação, devem rever-se na descrição atual da API associada os esquemas de operação e resposta aplicáveis ao início, à inspeção, aos resultados e ao cancelamento.

Antes de construir uma consulta, deve abrir-se o visualizador oficial do esquema Email Message History. No painel Table name, seleciona-se uma tabela e depois analisam-se General info, Fields e Custom Types. Como orientação, o esquema atual de Email apresenta exatamente três tabelas detetáveis: xdr_xge_att_data, xdr_xge_url_data e xdr_xge_events. O visualizador online continua a ser a autoridade para campos e tipos; este artigo não duplica deliberadamente uma lista de campos. Estas tabelas do Data Lake não são esquemas de resposta de /email/v1.

Antes de implementar, é necessário escolher a operação exata na descrição atual da API e rever método HTTP, caminho, esquema de pedido, esquema de resposta, permissão e limites documentados. Nunca se inventam caminhos de endpoint nem se deriva uma operação substituindo um nome.

O percurso segue de autenticação e routing de tenant para caixas de correio, clawback, quarentena, quarentena post-delivery e S/MIME.

Construir o contrato do pedido

A especificação revista usa um URL base regional terminado em /email/v1. Todos os pedidos do tenant exigem token bearer e X-Tenant-ID; chamadas JSON usam Content-Type: application/json. Ao host validado acrescenta-se apenas o caminho de produto documentado:

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

Antes de escritas em produção, deve executar-se uma leitura inofensiva. GET /mailboxes é uma operação de listagem na especificação revista. pageSize=1 limita apenas a primeira resposta e não prova que não existam páginas seguintes:

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

O teste passa com estado 200 e estruturas items e pages presentes. Não se registam corpos indiscriminadamente: até uma lista de caixas contém dados pessoais do tenant.

Considerar paginação, throttling e duração do token

Uma primeira página válida não é um inventário completo. Em GET /mailboxes, pages.nextKey contém a chave seguinte; esta é enviada com codificação URL como pageFromKey no pedido seguinte. O cliente continua até não existir nextKey, limita páginas e duração e deteta chaves repetidas. Para cada outra operação vale apenas o respetivo modelo de paginação atualmente documentado.

Throttling não é erro de esquema. Perante 429, devem respeitar-se os headers documentados de retry ou rate limit, usar backoff limitado com jitter e limitar tentativas e duração total. Não se repetem cegamente escritas, eliminações, libertações ou clawbacks: um timeout pode ocorrer depois de o servidor aceitar a operação.

Um token expirado é renovado pelo fluxo OAuth2. Um 401 não se contorna mudando tenant ou região. Perante 403, verificam-se função, permissão e associação ao tenant; perante 404, host regional, caminho documentado e ID. Outros 4xx são erros de pedido ou estado. O tratamento de 5xx deve ser limitado; primeiro determina-se o estado e possível efeito do servidor e só depois se repete de forma controlada.

Validar versão e entrada em produção

A especificação subjacente a este artigo foi revista na versão v1.4.0. A versão atual deve ser novamente verificada antes da implementação. Caminhos ou esquemas de v1.4.0 não são promessa para versões posteriores.

Antes da entrada em produção, documentar:

1. proprietário da credencial, função mínima, ID do tenant e host regional descoberto;
2. família escolhida e método, caminho e esquema atuais;
3. GET inofensivo com estado HTTP e resultado de esquema, sem token nem payload completo;
4. fim da paginação, comportamento 429, renovação do token e duração máxima de retry;
5. para cada mutação, idempotência, aprovação, efeito esperado, validação e forma de paragem.

A operação de negócio só é implementada após estes controlos passarem num tenant de teste ou registo controlado. OAuth2 e routing do tenant continuam a ser pré-requisitos comuns, não funcionalidades Sophos Email.