Skip to content
Cloudflare API
Start here
API Reference
Email Security
Investigate
Bulk
Cancel

Cancel a bulk action job

email_security.investigate.bulk.cancel.create(strjob_id, CancelCreateParams**kwargs) -> CancelCreateResponse
POST/accounts/{account_id}/email-security/investigate/bulk/{job_id}/cancel

Marks the job as cancelled and stops any pending message processing. The job record remains visible in list and detail endpoints.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
Accepted Permissions (at least one required)
Cloud Email Security: Write
ParametersExpand Collapse
account_id: str

Identifier.

maxLength32
job_id: str
formatuuid
ReturnsExpand Collapse
class CancelCreateResponse: …
action_params: ActionParams
One of the following:
class ActionParamsMove: …
destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]
One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: Literal["MOVE"]
expected_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
class ActionParamsRelease: …
type: Literal["RELEASE"]
action_type: Literal["MOVE", "RELEASE"]
One of the following:
"MOVE"
"RELEASE"
created_at: datetime
formatdate-time
job_id: str
formatuuid
messages_failed: int
messages_pending: int
messages_successful: int
search_params: SearchParams
Deprecatedaction_log: Optional[bool]

Deprecated, use GET /investigate/{investigate_id}/action_log instead. End of life: November 1, 2026.

alert_id: Optional[str]
delivery_status: Optional[Literal["delivered", "moved", "quarantined", 4 more]]

Delivery status of the message.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
detections_only: Optional[bool]
domain: Optional[str]
end: Optional[datetime]

End of search date range

formatdate-time
exact_subject: Optional[str]
final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action: Optional[Literal["PREVIEW", "QUARANTINE_RELEASED", "MOVED"]]
One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id: Optional[str]
metric: Optional[str]
query: Optional[str]
recipient: Optional[str]
sender: Optional[str]
start: Optional[datetime]

Beginning of search date range

formatdate-time
subject: Optional[str]
submissions: Optional[bool]
status: Literal["PENDING", "DISCOVERING", "PROCESSING", 4 more]
One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
"SKIPPED"
total_messages_discovered: int
comment: Optional[str]
completed_at: Optional[datetime]
formatdate-time
started_at: Optional[datetime]
formatdate-time
status_message: Optional[str]

Cancel a bulk action job

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
cancel = client.email_security.investigate.bulk.cancel.create(
    job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(cancel.job_id)
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "action_params": {
      "destination": "Inbox",
      "type": "MOVE",
      "expected_disposition": "MALICIOUS"
    },
    "action_type": "MOVE",
    "created_at": "2019-12-27T18:11:19.117Z",
    "job_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "messages_failed": 0,
    "messages_pending": 0,
    "messages_successful": 0,
    "search_params": {
      "action_log": true,
      "alert_id": "alert_id",
      "delivery_status": "delivered",
      "detections_only": true,
      "domain": "domain",
      "end": "2022-07-25T14:30:00Z",
      "exact_subject": "exact_subject",
      "final_disposition": "MALICIOUS",
      "message_action": "PREVIEW",
      "message_id": "message_id",
      "metric": "metric",
      "query": "query",
      "recipient": "recipient",
      "sender": "sender",
      "start": "2022-06-25T14:30:00Z",
      "subject": "subject",
      "submissions": true
    },
    "status": "PENDING",
    "total_messages_discovered": 0,
    "comment": "comment",
    "completed_at": "2019-12-27T18:11:19.117Z",
    "started_at": "2019-12-27T18:11:19.117Z",
    "status_message": "status_message"
  },
  "success": true
}
Returns Examples
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "action_params": {
      "destination": "Inbox",
      "type": "MOVE",
      "expected_disposition": "MALICIOUS"
    },
    "action_type": "MOVE",
    "created_at": "2019-12-27T18:11:19.117Z",
    "job_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "messages_failed": 0,
    "messages_pending": 0,
    "messages_successful": 0,
    "search_params": {
      "action_log": true,
      "alert_id": "alert_id",
      "delivery_status": "delivered",
      "detections_only": true,
      "domain": "domain",
      "end": "2022-07-25T14:30:00Z",
      "exact_subject": "exact_subject",
      "final_disposition": "MALICIOUS",
      "message_action": "PREVIEW",
      "message_id": "message_id",
      "metric": "metric",
      "query": "query",
      "recipient": "recipient",
      "sender": "sender",
      "start": "2022-06-25T14:30:00Z",
      "subject": "subject",
      "submissions": true
    },
    "status": "PENDING",
    "total_messages_discovered": 0,
    "comment": "comment",
    "completed_at": "2019-12-27T18:11:19.117Z",
    "started_at": "2019-12-27T18:11:19.117Z",
    "status_message": "status_message"
  },
  "success": true
}