Skip to content

Guide — Clawback

Overview

This guide explains how to use the Email Clawback API. After reading this guide, you should be able to claw back messages in Sophos Email and get the message clawback status.

Prerequisites

You must have a set of API credentials (service principal) to be able to call the Email Clawback API. For more information, see the relevant Getting Started guide:

Terminology

Before you use the Email Clawback API, here are a few terms you should know:

  • ID: The value of the x-sophos-email-id message header. This value can be derived from various Email query response in Live Discover in Threat Analysis Center.

Making API requests

You can make the API calls in the following sections using cURL. Follow the instructions on cURL's website to install this tool.

When using curl, a request to the Email Clawback API has the following general form:

curl -X <method> -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" <data-region>/<path>

The command includes the following placeholders:

  • <method>: The request method. For the Email Clawback API, this is either GET or POST.
  • <tenant-id>: The ID of the tenant you want to query.
  • <jwt>: The JWT access token returned when the IDP authenticates the service principal.
  • <data-region>: The regional API host in the data geography where the tenant data is located.
  • <path>: The request path for the API operation, for example, /email/v1/messages/{id}/status:.

The API descriptions in this guide only specify the request method and path. For example:

POST /email/v1/messages/{id}/clawback

To make an actual API request, you must expand this to the full form shown above.

Email Clawback operations

Clawback

Use this API to claw back a single email message from all or some recipients. To claw back from specific mailboxes, configure the mailbox addresses in a recipients list in the request body. If you don't configure a recipients list, you claw back from all recipient mailboxes of the message.

Note that this API is atomic, which means if one recipient isn't eligible for clawback, the request fails as a whole. Remove the non-eligible mailboxes from the recipients list and repeat the request.

POST /email/v1/messages/{id}/clawback

Request:

{
  "recipients": [
    "user1@sophos.com",
    "user2@sophos.com",
    "user3@sophos.com"
  ]
}

Multiple Clawback

Use this API to claw back multiple email messages. Configure the email IDs (x-sophos-email-id) in a messageIds list in the request body.

POST /email/v1/messages/clawback

Request:

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

Status

This API returns the latest status for each recipient mailbox, for example, Clawback successful, Clawback initiated, Quarantine, etc.

GET /email/v1/messages/{id}/status

Response:

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

Conclusion

See the Email Management API reference for a comprehensive description of this API.