Automatizar caixas de correio Sophos Email via API

A Sophos Email Management API cobre todo o ciclo de vida da caixa: pesquisar o inventário, criar caixas individualmente ou em lote, alterar nomes e relações e eliminar objetos. A sequência segura é sempre ler, comparar estado pretendido e real, fazer uma alteração direcionada e voltar a ler. Um estado HTTP de sucesso não basta em operações bulk ou de relações.

Confirmar pré-requisitos e propriedade

Este artigo pressupõe a introdução à Sophos Email Management API. Autenticação, validade do token, resolução do tenant e host regional constam de Autenticar a Sophos Email API e encaminhar para o tenant. Todos os caminhos exigem URL regional ${SOPHOS_API_HOST%/}/email/v1, Authorization: Bearer <access-token>, X-Tenant-ID: <tenant-uuid>, para JSON Content-Type: application/json, e UUID no lugar de {id}. Os esquemas verificados são da Email Management API v1.4.0; confirme sempre o contrato atual.

Antes de escrever, determine qual sistema possui o inventário. A sincronização de diretório continua autoritativa para objetos sincronizados. A API não substitui essa propriedade; alterações podem ser sobrescritas ou rejeitadas. A especificação documenta 409 ao renomear, eliminar individualmente ou alterar aliases ou delegados de uma caixa sincronizada. Altere a origem do diretório, sem forçar variantes ou repetições na API.

Inventariar e pesquisar todas as caixas

GET /mailboxes devolve items e pages com fromKey, nextKey, size, maxSize. pageSize suporta no máximo 50 registos. Codifique pages.nextKey para URL e envie-o como pageFromKey; só a ausência de nextKey conclui o inventário. Limite chaves repetidas, páginas e duração total.

Só é permitido um parâmetro de pesquisa por pedido: name, nameStartsWith, email, emailStartsWith, createdAfter, createdBefore, type, bulkSenderPrivilegeStatus, blocked, distributionListOwnedBy, alias, aliasesStartWith ou delegate. Os tipos são user, distributionList, publicFolder, sharedMailbox; os estados são neverRequested, approvalPending, approved, rejected, revoked. Não combine filtros exatos e de prefixo.

Guarde pelo menos id, type, email, name, createdAt, blocked. Também podem existir aliases, delegates, distributionListOwners, bulkSenderPrivilege, policies. Não registe estes dados pessoais sem filtragem.

Criar, ler e renomear caixas

Na criação, email tem formato de e-mail e 4–320 caracteres; name, 1–256. type aceita os quatro valores. A criação individual devolve 201; 409 indica que uma caixa ou alias já usa o endereço. Localize o objeto e resolva a propriedade em vez de contornar com outro endereço.

A criação bulk também devolve 201 quando apenas parte tem sucesso. Reconcilie items e errors com cada endereço pedido, guarde UUID corretos e corrija apenas os elementos falhados. Verifique cada objeto por GET /mailboxes/{id} quanto a type, email, name. Após renomear, confirme a resposta 201 com GET e o name esperado.

Alterar aliases, delegados e proprietários de listas

As três relações usam arrays JSON add e remove, inclusive em conjunto. Leia primeiro para evitar um delta vazio ou já aplicado.

A última operação aplica-se a distributionList. 200 pode significar sucesso parcial. Avalie added, removed, errors.failedToAdd, errors.failedToRemove e confirme por GET o delta em aliases, delegates ou distributionListOwners. Repita apenas valores falhados após corrigir a causa, nunca todo o pedido às cegas. Erros comuns: alias já usado ou inexistente e delegado sem caixa. 400 indica pedido/esquema, 404 ID/contexto do tenant e 409 documentado propriedade da sincronização.

Pedir privilégio de remetente em massa

POST /mailboxes/{id}/bulksender-privilege-request exige count inteiro, period como daily, weekly ou monthly, e purpose com 2–2048 caracteres. Descreva o uso real. O contrato não fixa máximo numérico para count; não invente um. A resposta 200 contém accepted; accepted: true confirma submissão, não aprovação. Acompanhe por GET bulkSenderPrivilege.bulkSenderPrivilegeStatus e só repita após verificar estado e motivo empresarial.

Eliminar sem repetições cegas

A eliminação individual usa DELETE /mailboxes/{id}. A resposta 200 contém deleted; a mesma classe também é documentada quando a caixa não existe. Verifique o booleano e o estado posterior.

POST /mailboxes/delete elimina até 20 UUID no array obrigatório items; a resposta 200 separa items bem-sucedidos e errors por id. Antes, exporte UUID e endereço e compare com inventário recente. Elimine objetos sincronizados na origem.

Nunca repita às cegas: após timeout ou erro inesperado, algumas ou todas as caixas podem já ter sido eliminadas. Verifique cada UUID por GET ou Sophos Fusion (anteriormente Sophos Central), reconstrua resultados por elemento e, após nova aprovação, envie só alvos ainda existentes.

Limites, erros e validação de produção

Sophos documenta 10 000 pedidos diários para Create, Update e Delete e 20 000 para Get; o guia afirma que o limite horário é igual ao diário. Alterações de nome, alias, delegado e proprietário contam como Update. Perante 429, pause dentro de limites; não aumente concorrência nem repita mutações automaticamente. Peça mais quota ao Sophos Support.

Antes da produção, teste: paginação completa e um filtro por pedido; limites de tipo, e-mail, nome e arrays antes do envio; reconciliação por elemento das respostas bulk e de relações; GET ou inventário após cada escrita; tratamento separado de 400, 404, 409, 429, 5xx; nenhuma repetição automática de Delete ou outra operação não idempotente após resultado incerto. Assim, a API permanece uma ferramenta de automação, não uma segunda fonte de verdade concorrente.