Clawback message¶

POST/messages/{id}/clawback

Clawback message (can clawback message for specific recipients).

Required permissionxgemail.msghistory:write

Parameters¶

Name	In	Type	Required	Description
`X-Tenant-ID`	header	string (uuid)	Yes	Tenant ID.
`id`	path	string	Yes	ID from 'X-Sophos-Email-ID' MIME header.

Request body¶

Content type: application/json

Request body fields

recipientsarray of string

Target email addresses. If not specified, clawback is attempted for all recipients.
Must contain at most 500 items.

reasonstring

Clawback reason.
Must be one of: malware, phishing, spam, unwanted.

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X POST "https://api-<data-region>.central.sophos.com/email/v1/messages/<id>/clawback" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"recipients\": [
    \"user_bob@sophos.com\"
  ],
  \"reason\": \"phishing\"
}"

import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/email/v1/messages/<id>/clawback",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={'recipients': ['user_bob@sophos.com'], 'reason': 'phishing'},
)
print(response.json())

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "recipients": [
    "user_bob@sophos.com"
  ],
  "reason": "phishing"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/email/v1/messages/<id>/clawback" -Headers $headers -Body $body -ContentType "application/json"

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/email/v1/messages/<id>/clawback", strings.NewReader(`{
  "recipients": [
    "user_bob@sophos.com"
  ],
  "reason": "phishing"
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

const response = await fetch("https://api-<data-region>.central.sophos.com/email/v1/messages/<id>/clawback", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "recipients": [
    "user_bob@sophos.com"
  ],
  "reason": "phishing"
}),
});
const data = await response.json();
console.log(data);

Responses¶

`202` — Clawback request accepted.¶

Response fields

idstring (uuid)

ID from 'X-Sophos-Email-ID' MIME header.

recipientsarray of string

List of recipients for whom the clawback request was accepted.

errorsarray of object

List of recipients for whom clawback request was not accepted.

Show child attributesHide child attributes

recipientstringrequired

errorstringrequired

Reason for error.

Errors¶

Status	Meaning
`400`	Bad request.
`401`	Authentication required.
`403`	Authorization required.
`404`	Not found.
`500`	Unexpected error.

All error responses share the same shape — see the error response object.

Response examples¶

`202`¶

{
  "id": "15a7f8ea-691c-4f03-862e-3cefb102818e",
  "recipients": [
    "user_bob@sophos.com"
  ],
  "errors": [
    {
      "recipient": "user_bob@sophos.com",
      "error": "clawbackNotSupported"
    }
  ]
}

See the guide for a narrative walkthrough of this API.