Zarządzanie kwarantanną po dostarczeniu Sophos Email przez API

Kwarantanna po dostarczeniu zawiera wiadomości, które najpierw dostarczono, a następnie Post-Delivery Protection usunęło ze skrzynki. Jej API używa więc osobnej rodziny ścieżek /post-delivery-quarantine. Podobne endpointy /quarantine dotyczą zwykłej kwarantanny przed dostarczeniem i nie są zamienne.

Bezpieczna kolejność to: wąskie wyszukiwanie, weryfikacja wyniku i odbiorcy, kontrola wiadomości lub załączników, zmiana wyłącznie zatwierdzonych ID i ponowne sprawdzenie stanu. Wprowadzenie do Email Management API objaśnia rodziny API. Przygotowanie OAuth2, tenanta i routingu regionalnego dostarcza używane wartości dostępowe.

Wymagania i baza żądań

Post-Delivery Protection musi być aktywne dla domeny, service principal skonfigurowany, a jego uprawnienie do Post-Delivery Quarantine potwierdzone. Należy przejąć tylko zweryfikowane wartości:

SOPHOS_ACCESS_TOKEN: aktualny token Bearer;
SOPHOS_TENANT_ID: UUID tenanta docelowego;
SOPHOS_API_HOST: host regionalny ustalony dokładnie dla tego tenanta.

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

Każde wywołanie wysyła nagłówek Authorization z Bearer, po którym następuje aktualny SOPHOS_ACCESS_TOKEN, nagłówek X-Tenant-ID z wartością SOPHOS_TENANT_ID oraz Accept: application/json, a dla JSON także Content-Type: application/json. Tenant, token i host muszą być zgodne. Błąd 403 rozwiązuje się, sprawdzając uprawnienie API i przypisanie tenanta, a nie testując inne tenanty. Przykłady oparto na Email Management API v1.4.0; przed wdrożeniem trzeba ponownie sprawdzić aktualny kontrakt.

Precyzyjne wyszukiwanie wiadomości

POST /post-delivery-quarantine/messages/search wymaga znaczników czasu beginDate i endDate. Opcjonalne są page (od 1), pageSize (domyślnie 50, maksymalnie 100), sort i filter. Udokumentowane filtry: id, fromContains, toContains, subjectContains, attachmentNameContains, sizeInMBGreaterThan, sizeInMBLowerThan, productType, reason, hasAnyAttachment. productType przyjmuje mailflow, gateway lub ems, a reason: malware, maliciousUrl lub onDemand.

Rozpocznij od krótkiego zakresu UTC i znanych cech:

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"]
  }
}

Zastąp czas i adres zatwierdzonym zakresem dochodzenia. Odpowiedź zawiera items i pages. Zacznij od strony 1 i zwiększaj page dokładnie o jeden. Jeśli pole pages.total jest obecne, zatrzymaj się po osiągnięciu tej liczby; w przeciwnym razie zatrzymaj się na pierwszej pustej stronie lub stronie z mniejszą liczbą elementów niż żądane pageSize. Przed rozpoczęciem ustaw maksymalną liczbę stron i czas działania, a wyszukiwanie uznaj za niekompletne, jeśli stronicowanie jest błędne, powtarza się, nie postępuje lub osiągnie którykolwiek limit. Przed zmianą porównaj co najmniej id, forRecipient, quarantinedAt, reason, temat i tenant. id pochodzi z nagłówka MIME X-Sophos-Email-ID, a nie z MIME Message-ID ani o365MessageId.

Kontrola treści i załączników

GET /post-delivery-quarantine/messages/{id}/preview zwraca headers oraz, jeśli istnieją, htmlBody i textBody.
GET /post-delivery-quarantine/messages/{id}/attachments?page=1&pageSize=50 zwraca nazwy załączników i sizeInBytes z pages. Domyślnie jest to strona 1 i 50 elementów; odpowiedź może obsłużyć do 500 elementów na stronę.

Podgląd może zawierać złośliwe i poufne dane. Nie renderuj aktywnie HTML, nie otwieraj odsyłaczy i nie zapisuj odpowiedzi bez filtrowania. Lista nie pobiera jeszcze pliku.

Do pobrania wyślij nazwy załączników do POST /post-delivery-quarantine/messages/{id}/attachments/download. Pominięcie attachments pobiera wszystkie załączniki, dlatego lepiej podać jawną listę:

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

Odpowiedź zawiera id zadania i status. Użyj tego id jako downloadId:

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

Gdy status ma wartość processing, odpytuj w ograniczonych odstępach. Przy completed odpowiedź zawiera nazwy i url; dla chronionego ZIP może zawierać też password. Przy failed sprawdź error, zamiast bez końca ponawiać żądanie. Pliki otwieraj tylko w izolowanym środowisku, a URL i hasła nie zapisuj w logach ani zgłoszeniach.

Zwalnianie lub usuwanie

Obie operacje zapisu przyjmują maksymalnie 50 elementów w items. Każdy wymaga post-delivery id; forRecipients ogranicza akcję do odbiorców. Bez forRecipients przewodnik stosuje akcję do wszystkich odbiorców wiadomości.

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

POST /post-delivery-quarantine/messages/release kolejkuje wiadomości do zwolnienia. HTTP 202 oznacza przyjęto, a nie potwierdzenie w skrzynce.
POST /post-delivery-quarantine/messages/delete usuwa wiadomości. Sprawdzona specyfikacja zwraca przy powodzeniu HTTP 200, więc usunięcie nie jest zadaniem pobierania.

Przed zwolnieniem udokumentuj treść, zakres odbiorców i zgodę. Przed każdą z operacji zapisu zachowaj lub wyeksportuj dowody potrzebne w dochodzeniu. Dla pomyślnego delete nie udokumentowano operacji API cofnięcia ani przywrócenia; przed tym nieodwracalnym krokiem wymagaj zatwierdzenia usunięcia i eskaluj wszelkie wątpliwości. release ponownie dostarcza wiadomość, ale nie umożliwia powtórzenia pierwotnego wycofania jej ze skrzynki. Nie ponawiaj automatycznie po timeout lub 5xx, ponieważ skutek serwerowy mógł już nastąpić.

Walidacja wyników i błędów częściowych

Zwolnienie i usunięcie zwracają osobne tablice items i errors. Przed wysłaniem rozwiń zatwierdzone żądanie do konkretnych par (id, recipient), a następnie uzgodnij każdą żądaną parę dokładnie raz w obu tablicach łącznie: poprawny wpis items zawiera tylko id i recipient, a błędny wpis errors zawiera id, recipient i error. Uznaj odpowiedź za nieprawidłową i zastosuj fail-closed, jeśli brakuje żądanej pary, para jest zduplikowana, występuje w obu tablicach lub zwrócono parę nieobjętą żądaniem. Dla każdej pary zapisz wynik i zwrócone error, bez treści i tokenów. Ponawiaj tylko nieudane pary, które po kontroli stanu nadal są ważne i zostały ponownie zatwierdzone; nigdy nie ponawiaj par udanych ani niejednoznacznych.

Następnie wyszukaj ponownie ten sam id i odbiorcę. Po poprawnym usunięciu element nie może występować w wybranym zakresie; ta walidacja potwierdza destrukcyjny rezultat, a nie ścieżkę odzyskiwania. Po przyjęciu zwolnienia poczekaj na zmianę stanu i potwierdź w skrzynce docelowej, że wiadomość wróciła właściwemu odbiorcy. To potwierdzenie dostarczenia nie dowodzi, że pierwotne wycofanie można wykonać ponownie. Jeśli element nadal występuje w wynikach albo wiadomości nie ma w skrzynce, sprawdź odbiorcę, stan PDP i zwrócony błąd przed ponowną oceną tej części.

brak wyniku: sprawdź zakres UTC, stronę, tenant, typ ID i stan PDP;
404 dla podglądu, załączników lub zadania: sprawdź host regionalny, ścieżkę post-delivery i właściwe ID;
pobieranie failed: sprawdź error i porównaj nazwy z bieżącą listą;
mieszana odpowiedź zbiorcza: uzgodnij wszystkie żądane pary i ponów tylko nadal ważne, ponownie zatwierdzone nieudane pary; zastosuj fail-closed przy wynikach brakujących, zduplikowanych, sprzecznych lub nieoczekiwanych;
wynik tylko w zwykłej kwarantannie: kontynuuj przez /quarantine, nie przenoś wiadomości do rodziny post-delivery.

Dzięki temu automatyzacja pozostaje związana z tenantem, świadoma stanu i powtarzalna bez mieszania obu rodzajów kwarantanny.