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

Bulk

List bulk action jobs
GET/accounts/{account_id}/email-security/investigate/bulk
Create a bulk action job
POST/accounts/{account_id}/email-security/investigate/bulk
Get bulk action job details
GET/accounts/{account_id}/email-security/investigate/bulk/{job_id}
Delete a bulk action job
DELETE/accounts/{account_id}/email-security/investigate/bulk/{job_id}
ModelsExpand Collapse
BulkListResponse object { action_params, action_type, created_at, 11 more }
action_params: object { destination, type, expected_disposition } or object { type }
One of the following:
Move object { destination, type, expected_disposition }
destination: "Inbox" or "JunkEmail" or "DeletedItems" or 2 more
One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
expected_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Release object { type }
type: "RELEASE"
action_type: "MOVE" or "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
job_id: string
formatuuid
messages_failed: number
messages_pending: number
messages_successful: number
search_params: object { action_log, alert_id, delivery_status, 14 more }
Deprecatedaction_log: optional boolean

Use GET /investigate/{investigate_id}/action_log instead.

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

alert_id: optional string
delivery_status: optional "delivered" or "moved" or "quarantined" or 4 more

Delivery status of the message.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
detections_only: optional boolean
domain: optional string
end: optional string

End of search date range

formatdate-time
exact_subject: optional string
final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action: optional "PREVIEW" or "QUARANTINE_RELEASED" or "MOVED"
One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id: optional string
metric: optional string
query: optional string
recipient: optional string
sender: optional string
start: optional string

Beginning of search date range

formatdate-time
subject: optional string
submissions: optional boolean
status: "PENDING" or "DISCOVERING" or "PROCESSING" or 4 more
One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
"SKIPPED"
total_messages_discovered: number
comment: optional string
completed_at: optional string
formatdate-time
started_at: optional string
formatdate-time
status_message: optional string
BulkCreateResponse object { action_params, action_type, created_at, 11 more }
action_params: object { destination, type, expected_disposition } or object { type }
One of the following:
Move object { destination, type, expected_disposition }
destination: "Inbox" or "JunkEmail" or "DeletedItems" or 2 more
One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
expected_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Release object { type }
type: "RELEASE"
action_type: "MOVE" or "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
job_id: string
formatuuid
messages_failed: number
messages_pending: number
messages_successful: number
search_params: object { action_log, alert_id, delivery_status, 14 more }
Deprecatedaction_log: optional boolean

Use GET /investigate/{investigate_id}/action_log instead.

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

alert_id: optional string
delivery_status: optional "delivered" or "moved" or "quarantined" or 4 more

Delivery status of the message.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
detections_only: optional boolean
domain: optional string
end: optional string

End of search date range

formatdate-time
exact_subject: optional string
final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action: optional "PREVIEW" or "QUARANTINE_RELEASED" or "MOVED"
One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id: optional string
metric: optional string
query: optional string
recipient: optional string
sender: optional string
start: optional string

Beginning of search date range

formatdate-time
subject: optional string
submissions: optional boolean
status: "PENDING" or "DISCOVERING" or "PROCESSING" or 4 more
One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
"SKIPPED"
total_messages_discovered: number
comment: optional string
completed_at: optional string
formatdate-time
started_at: optional string
formatdate-time
status_message: optional string
BulkGetResponse object { action_params, action_type, created_at, 11 more }
action_params: object { destination, type, expected_disposition } or object { type }
One of the following:
Move object { destination, type, expected_disposition }
destination: "Inbox" or "JunkEmail" or "DeletedItems" or 2 more
One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
expected_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Release object { type }
type: "RELEASE"
action_type: "MOVE" or "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
job_id: string
formatuuid
messages_failed: number
messages_pending: number
messages_successful: number
search_params: object { action_log, alert_id, delivery_status, 14 more }
Deprecatedaction_log: optional boolean

Use GET /investigate/{investigate_id}/action_log instead.

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

alert_id: optional string
delivery_status: optional "delivered" or "moved" or "quarantined" or 4 more

Delivery status of the message.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
detections_only: optional boolean
domain: optional string
end: optional string

End of search date range

formatdate-time
exact_subject: optional string
final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action: optional "PREVIEW" or "QUARANTINE_RELEASED" or "MOVED"
One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id: optional string
metric: optional string
query: optional string
recipient: optional string
sender: optional string
start: optional string

Beginning of search date range

formatdate-time
subject: optional string
submissions: optional boolean
status: "PENDING" or "DISCOVERING" or "PROCESSING" or 4 more
One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
"SKIPPED"
total_messages_discovered: number
comment: optional string
completed_at: optional string
formatdate-time
started_at: optional string
formatdate-time
status_message: optional string
BulkDeleteResponse object { id }
id: string
formatuuid

BulkCancel

Cancel a bulk action job
POST/accounts/{account_id}/email-security/investigate/bulk/{job_id}/cancel
ModelsExpand Collapse
CancelCreateResponse object { action_params, action_type, created_at, 11 more }
action_params: object { destination, type, expected_disposition } or object { type }
One of the following:
Move object { destination, type, expected_disposition }
destination: "Inbox" or "JunkEmail" or "DeletedItems" or 2 more
One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
expected_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Release object { type }
type: "RELEASE"
action_type: "MOVE" or "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
job_id: string
formatuuid
messages_failed: number
messages_pending: number
messages_successful: number
search_params: object { action_log, alert_id, delivery_status, 14 more }
Deprecatedaction_log: optional boolean

Use GET /investigate/{investigate_id}/action_log instead.

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

alert_id: optional string
delivery_status: optional "delivered" or "moved" or "quarantined" or 4 more

Delivery status of the message.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
detections_only: optional boolean
domain: optional string
end: optional string

End of search date range

formatdate-time
exact_subject: optional string
final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action: optional "PREVIEW" or "QUARANTINE_RELEASED" or "MOVED"
One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id: optional string
metric: optional string
query: optional string
recipient: optional string
sender: optional string
start: optional string

Beginning of search date range

formatdate-time
subject: optional string
submissions: optional boolean
status: "PENDING" or "DISCOVERING" or "PROCESSING" or 4 more
One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
"SKIPPED"
total_messages_discovered: number
comment: optional string
completed_at: optional string
formatdate-time
started_at: optional string
formatdate-time
status_message: optional string

BulkMessages

List messages for a bulk action job
GET/accounts/{account_id}/email-security/investigate/bulk/{job_id}/messages
ModelsExpand Collapse
MessageListResponse object { action_params, action_type, created_at, 9 more }
action_params: object { client_recipient, destination, type, expected_disposition } or object { client_recipient, type }
One of the following:
Move object { client_recipient, destination, type, expected_disposition }
client_recipient: string
destination: "Inbox" or "JunkEmail" or "DeletedItems" or 2 more
One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
expected_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Release object { client_recipient, type }
client_recipient: string
type: "RELEASE"
action_type: "MOVE" or "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
message_id: string
formatuuid
postfix_id: string
retry_count: number
status: "PENDING" or "DISCOVERING" or "PROCESSING" or 4 more
One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
"SKIPPED"
alert_id: optional string
email_message_id: optional string
processed_at: optional string
formatdate-time
retry_after: optional string

When to retry the action if it failed

formatdate-time
status_message: optional string