Hoppa till innehållet
Avanet

Kör och verifiera Sophos Email-clawback via API

Sophos Email

Clawback API tar bort redan levererade Sophos Email-meddelanden från berättigade brevlådor. Det säkra flödet har två faser: skicka clawback en gång och fråga sedan GET /messages/{id}/status tills varje accepterad mottagare har ett slutresultat. Ett 202 bekräftar att jobbet accepterats, inte att det lyckats i brevlådan.

Fastställ förutsättningar och gränser

Du behöver en konfigurerad service principal, en giltig OAuth2 bearer-token, måltenantens UUID och dess upptäckta regionala API-värd. Introduktionen till Email Management API beskriver operationsfamiljer och det säkra lästestet. Den planerade runbooken Autentisering och tenantrouting för Sophos Email API samlar token, tenantupplösning och regional routing.

Exemplen använder redan validerade variabler:

EMAIL_API_HOST="${SOPHOS_API_HOST%/}/email/v1"
SOPHOS_EMAIL_ID="15a7f8ea-691c-4f03-862e-3cefb102818e"

SOPHOS_API_HOST är den regionala värd som upptäckts för tenanten, inte en gissad värd. Ersätt ofarliga exemplet SOPHOS_EMAIL_ID. Varje anrop använder Authorization: Bearer *** och X-Tenant-ID; hemligheter och fullständiga meddelandedata får inte hamna i kod, loggar eller ärenden.

Clawback kräver även rätt PDP/clawback-behörighet och en fungerande leverantörsanslutning. Endast meddelanden som levererats framgångsrikt till berättigade brevlådor och berättigade mottagare kan åtgärdas. Post-Delivery Protection i Sophos Fusion behandlar anslutningen, On demand clawback i gränssnittet och Auto search and remediate. Dessa UI-flöden är skilda från API:t och ersätter inte dess statuspolling.

Hämta rätt x-sophos-email-id

Sökvägsparametern {id} är värdet i MIME-headern X-Sophos-Email-ID, inte Internet-Message-ID, ämnesraden eller ett godtyckligt UUID. Sophos anger också att värdet kan härledas från olika Email-frågesvar i Live Discover i Threat Analysis Center. Denna runbook hittar inte på ett frågeschema: hämta x-sophos-email-id från tillförlitliga meddelandebevis och kontrollera minst tenant, meddelande och berörda mottagare.

Sätt värdet i SOPHOS_EMAIL_ID utan blanksteg eller radbrytning. För flera meddelanden dokumenterar du varje ID med godkännande och ärende; bygg inte en lista enbart från liknande ämnesrader.

Återkalla ett meddelande

Den dokumenterade endpointen är POST /messages/{id}/clawback. Utan recipients försöker Sophos för alla mottagare. Använd bara detta breda omfång när alla ingår i incidenten. Ange adresserna i en pilot; specifikationen tillåter högst 500 poster.

Valfri reason är malware, phishing, spam eller unwanted:

{
  "reason": "phishing",
  "recipients": [
    "user1@example.com",
    "user2@example.com"
  ]
}

Skicka POST exakt en gång och skydda svaret:

REQUEST_FILE=$(mktemp) || exit 1
RESPONSE_FILE=$(mktemp) || exit 1
trap 'rm -f "$REQUEST_FILE" "$RESPONSE_FILE"' EXIT

cat >"$REQUEST_FILE" <<'JSON'
{
  "reason": "phishing",
  "recipients": ["user1@example.com", "user2@example.com"]
}
JSON

HTTP_STATUS=$(
  printf 'header = "Authorization: Bearer %s"\n' "$SOPHOS_ACCESS_TOKEN" |
  curl --silent --show-error --config - \
    --output "$RESPONSE_FILE" \
    --write-out '%{http_code}' \
    --request POST \
    --header "X-Tenant-ID: $SOPHOS_TENANT_ID" \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-binary "@$REQUEST_FILE" \
    "$EMAIL_API_HOST/messages/$SOPHOS_EMAIL_ID/clawback"
)
printf 'Clawback submission returned HTTP %s\n' "$HTTP_STATUS"

Förvänta 202. Svaret skiljer accepterade recipients från errors, var och en med recipient och error. Dokumentera acceptans per mottagare utan att exponera hela svaret. Sophos beskriver det mottagarbegränsade enskilda anropet som atomärt: en obehörig mottagare kan få hela anropet att misslyckas. Kontrollera orsaken, ta bara bort mottagaren när det är motiverat och skicka sedan ett medvetet nytt anrop.

Återkalla flera meddelanden

För flera meddelanden dokumenterar Sophos POST /messages/clawback med listan messageIds. Varje post är ett x-sophos-email-id:

{
  "messageIds": [
    "e4fa988e-76f6-11ee-b962-0242ac120002",
    "eb9df47e-76f6-11ee-b962-0242ac120002",
    "ef790f0276f611eeb9620242ac120002"
  ]
}

Massanropet minskar antalet anrop, inte kontrollerna. Dokumentera acceptans och status för varje ID. Om bara vissa mottagare av ett meddelande berörs använder du den enskilda endpointen med recipients; den dokumenterade masspayloaden saknar mottagarlista.

Polla till slutresultat per mottagare

Använd GET /messages/{id}/status för varje ID. Under items finns recipient och status:

{
  "items": [
    {"recipient": "user1@example.com", "status": "clawbackSuccessful"},
    {"recipient": "user2@example.com", "status": "clawbackFailed"}
  ]
}

clawbackProcessing är ett mellanläge. Dokumentera clawbackSuccessful eller clawbackFailed som terminalt resultat per mottagare. Schemat kan också returnera accepted, quarantined, deliverySuccessful eller deliveryFailed; tolka dem inte som lyckad clawback.

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' \
    "$EMAIL_API_HOST/messages/$SOPHOS_EMAIL_ID/status"
)
printf 'Clawback status returned HTTP %s\n' "$HTTP_STATUS"

Polla med begränsat intervall och jitter så länge slutresultat saknas. Begränsa antal försök och total tid. Vid timeout är resultatet okänt, inte misslyckat: skicka ingen ny POST förrän en senare GET eller Sophos Fusion har klarlagt effekten av den första.

Hantera delresultat och fel säkert

  • Inte berättigad eller redan åtgärdad: kontrollera meddelande, domän, leverans och mottagare. Upprepade POST reparerar inte en tidigare framgång. Efter atomärt avslag tar du bara bort obehöriga adresser efter kontroll.
  • Blandade statusar: behåll clawbackSuccessful för lyckade mottagare och undersök clawbackFailed separat. Rapportera inte hela jobbet som lyckat och bearbeta inte framgångar igen.
  • 400: kontrollera ID, JSON, tillåten reason och mottagare; upprepa inte oförändrat.
  • 401 eller 403: förnya via OAuth2 eller kontrollera roll, clawback-behörighet och tenanttilldelning. Byt aldrig tenant eller region som experiment.
  • 404: jämför regional värd, dokumenterad sökväg och x-sophos-email-id med bevisen.
  • Throttling (429): följ dokumenterad vägledning och sakta ned GET med begränsad backoff och jitter. Upprepa aldrig en POST blint.
  • Timeout eller 5xx: servern kan ha accepterat jobbet. Fråga samma ID först, begränsa försök och tid och skicka bara på nytt när effekten är känd.

Verifieringen är klar när inskickningsresultat, accepterade och avvisade mottagare samt varje terminalt resultat registrerats för varje ID. Kontrollera dessutom brevlådan och Post-Delivery Quarantine i rätt tenant. API-svaret är fortsatt den maskinläsbara grunden; UI-clawback, automatisk PDP och rapporter är separata driftvägar.