Gerir a quarentena pós-entrega do Sophos Email através da API

A quarentena pós-entrega contém mensagens entregues primeiro e depois removidas da caixa de correio pelo Post-Delivery Protection. A API utiliza, por isso, a família de caminhos separada /post-delivery-quarantine. Os endpoints semelhantes em /quarantine dizem respeito à quarentena normal antes da entrega e não são intercambiáveis.

A sequência segura é pesquisar com precisão, verificar resultado e destinatário, inspecionar mensagem ou anexos, alterar apenas os ID aprovados e voltar a consultar o estado. Introdução à Email Management API contextualiza as famílias. Preparar OAuth2, tenant e encaminhamento regional fornece os valores de acesso usados aqui.

Estabelecer pré-requisitos e base dos pedidos

O Post-Delivery Protection tem de estar ativo para o domínio, tem de existir um service principal e a sua permissão de Post-Delivery Quarantine deve estar confirmada. Utilize apenas estes valores validados:

SOPHOS_ACCESS_TOKEN: token Bearer atual;
SOPHOS_TENANT_ID: UUID do tenant de destino;
SOPHOS_API_HOST: host regional descoberto para esse tenant específico.

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

Cada chamada envia o cabeçalho Authorization com Bearer seguido do SOPHOS_ACCESS_TOKEN atual, o cabeçalho X-Tenant-ID com o valor SOPHOS_TENANT_ID e Accept: application/json; os pedidos JSON enviam também Content-Type: application/json. Tenant, token e host têm de corresponder. Resolva 403 verificando permissão de API e atribuição do tenant, não experimentando outros tenants. Os exemplos baseiam-se na Email Management API v1.4.0 analisada; reveja o contrato atual antes da implementação.

Pesquisar mensagens pós-entrega com precisão

POST /post-delivery-quarantine/messages/search exige beginDate e endDate. São opcionais page (a partir de 1), pageSize (predefinição 50, máximo 100), sort e filter. Filtros documentados: id, fromContains, toContains, subjectContains, attachmentNameContains, sizeInMBGreaterThan, sizeInMBLowerThan, productType, reason, hasAnyAttachment. productType aceita mailflow, gateway ou ems; reason aceita malware, maliciousUrl ou onDemand.

Comece com uma janela UTC curta e atributos conhecidos:

POST /email/v1/post-delivery-quarantine/messages/search

{
  "beginDate": "2026-09-15T08:00:00.000Z",
  "endDate": "2026-09-15T09:00:00.000Z",
  "page": 1,
  "pageSize": 50,
  "sort": ["quarantinedAt:DESC"],
  "filter": {
    "toContains": "user@example.com",
    "reason": ["onDemand"]
  }
}

Substitua hora e endereço pelo âmbito aprovado. A resposta contém items e pages. Comece na página 1 e incremente page exatamente em um. Se pages.total estiver presente, pare ao atingir esse total; caso contrário, pare na primeira página vazia ou com menos itens do que o pageSize pedido. Defina previamente limites máximos de páginas e de tempo de execução e marque a pesquisa como incompleta se a paginação for inválida, se repetir, não avançar ou atingir um dos limites. Antes de alterar, compare pelo menos id, forRecipient, quarantinedAt, reason, assunto e tenant. O id vem do cabeçalho MIME X-Sophos-Email-ID, não do Message-ID MIME nem de o365MessageId.

Inspecionar conteúdo e anexos

GET /post-delivery-quarantine/messages/{id}/preview devolve headers e, quando existirem, htmlBody e textBody.
GET /post-delivery-quarantine/messages/{id}/attachments?page=1&pageSize=50 devolve nomes e sizeInBytes com pages. As predefinições são página 1 e 50 itens; a resposta pode suportar até 500 itens por página.

A pré-visualização pode conter conteúdo malicioso e confidencial. Não renderize HTML ativamente, não abra links nem registe respostas sem filtragem. A listagem ainda não transfere ficheiros.

Para transferir, envie os nomes dos anexos para POST /post-delivery-quarantine/messages/{id}/attachments/download. Sem attachments, a tarefa transfere todos; prefira uma lista explícita:

{
  "attachments": ["suspect-document.zip"]
}

A resposta contém id e status da tarefa. Esse id é o downloadId para:

GET /email/v1/post-delivery-quarantine/downloads/{downloadId}/status

Enquanto status for processing, consulte com intervalo limitado. Com completed, a resposta contém nomes e url; num ZIP protegido pode também existir password. Com failed, analise error em vez de reiniciar indefinidamente. Abra ficheiros apenas num ambiente isolado e não coloque URL nem palavra-passe em registos ou tickets.

Libertar ou eliminar

Ambas as operações aceitam no máximo 50 elementos em items. Cada um requer o id pós-entrega; forRecipients limita a ação a destinatários específicos. Sem forRecipients, o guia aplica-a a todos os destinatários da mensagem.

{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "forRecipients": ["user@example.com"]
    }
  ]
}

POST /post-delivery-quarantine/messages/release coloca mensagens em fila para libertação. HTTP 202 significa aceite, não confirmado na caixa.
POST /post-delivery-quarantine/messages/delete elimina mensagens. A especificação revista devolve HTTP 200 com sucesso; não trate esta eliminação como tarefa de transferência.

Antes da libertação, documente conteúdo, âmbito de destinatários e aprovação. Preserve ou exporte as provas necessárias à investigação antes de qualquer operação de escrita. Um delete bem-sucedido não tem uma operação API documentada para anular ou restaurar; exija a aprovação da eliminação e escale qualquer dúvida antes desse passo irreversível. Um release volta a entregar a mensagem, mas não torna repetível a retirada original da caixa de correio. Não repita cegamente após timeout ou 5xx: o efeito no servidor pode já ter ocorrido.

Validar resultados e falhas parciais

Libertação e eliminação devolvem arrays separados items e errors. Antes de enviar, expanda o pedido aprovado em pares concretos (id, recipient) e reconcilie cada par pedido exatamente uma vez entre os dois arrays: uma entrada bem-sucedida de items contém apenas id e recipient, enquanto uma entrada falhada de errors contém id, recipient e error. Considere a resposta inválida e aplique fail-closed se faltar um par pedido, se estiver duplicado, se surgir em ambos os arrays ou se for devolvido um par não pedido. Registe o resultado e o error devolvido para cada par, sem conteúdo ou tokens. Repita apenas pares falhados que continuem válidos após a verificação do estado e tenham sido novamente aprovados; nunca repita pares bem-sucedidos ou ambíguos.

Pesquise depois novamente o mesmo id e destinatário. Após eliminação bem-sucedida, o item já não deve surgir no âmbito escolhido; esta validação confirma o resultado destrutivo, não um meio de recuperação. Após libertação aceite, aguarde a mudança de estado e confirme na caixa de destino que a mensagem regressou ao destinatário previsto. Essa confirmação de entrega não prova que a retirada original possa ser executada novamente. Se o item continuar na pesquisa ou a mensagem não estiver na caixa, verifique destinatário, estado PDP e erro antes de reavaliar essa parte.

sem resultado: verifique janela UTC, página, tenant, tipo de ID e estado PDP;
404 em pré-visualização, anexos ou tarefa: verifique host regional, caminho post-delivery e ID;
transferência failed: analise error e compare nomes com a lista atual;
resposta em massa mista: reconcilie todos os pares pedidos e repita apenas falhas ainda válidas e novamente aprovadas; aplique fail-closed a resultados em falta, duplicados, contraditórios ou inesperados;
resultado apenas na quarentena normal: prossiga com /quarantine, sem transferir a mensagem para post-delivery.

Assim, a automatização permanece associada ao tenant, consciente do estado e repetível, sem confundir as duas quarentenas.