Skip to content
Cloudflare API
Start here
API Reference
Email Security

Investigate

Search email messages
email_security.investigate.list(InvestigateListParams**kwargs) -> SyncV4PagePaginationArray[InvestigateListResponse]
GET/accounts/{account_id}/email-security/investigate
Get message details
email_security.investigate.get(strinvestigate_id, InvestigateGetParams**kwargs) -> InvestigateGetResponse
GET/accounts/{account_id}/email-security/investigate/{investigate_id}
ModelsExpand Collapse
class InvestigateListResponse: …
id: str

Unique identifier for a message retrieved from investigation.

Deprecatedaction_log: List[ActionLog]

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

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

completed_at: datetime

Timestamp when action completed.

formatdate-time
operation: Literal["MOVE", "RELEASE", "RECLASSIFY", 3 more]

Type of action performed.

One of the following:
"MOVE"
"RELEASE"
"RECLASSIFY"
"SUBMISSION"
"QUARANTINE_RELEASE"
"PREVIEW"
Deprecatedcompleted_timestamp: Optional[str]

Use completed_at instead.

Deprecated, use completed_at instead. End of life: November 1, 2026.

properties: Optional[ActionLogProperties]

Additional properties for the action.

folder: Optional[str]

Target folder for move operations.

requested_by: Optional[str]

User who requested the action.

status: Optional[str]

Status of the action.

client_recipients: List[str]
detection_reasons: List[str]
is_phish_submission: bool
is_quarantined: bool
postfix_id: str

The identifier of the message.

properties: Properties

Message processing properties.

allowlisted_pattern: Optional[str]

Pattern that allowlisted this message.

allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]

Type of allowlist pattern.

One of the following:
"quarantine_release"
"acceptable_sender"
"allowed_sender"
"allowed_recipient"
"domain_similarity"
"domain_recency"
"managed_acceptable_sender"
"outbound_ndr"
blocklisted_message: Optional[bool]

Whether message was blocklisted.

blocklisted_pattern: Optional[str]

Pattern that blocklisted this message.

whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]

Legacy field for allowlist pattern type.

One of the following:
"quarantine_release"
"acceptable_sender"
"allowed_sender"
"allowed_recipient"
"domain_similarity"
"domain_recency"
"managed_acceptable_sender"
"outbound_ndr"
Deprecatedts: str

Use scanned_at instead.

Deprecated, use scanned_at instead. End of life: November 1, 2026.

alert_id: Optional[str]
delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 8 more]]
One of the following:
"DIRECT"
"BCC"
"JOURNAL"
"REVIEW_SUBMISSION"
"DMARC_UNVERIFIED"
"DMARC_FAILURE_REPORT"
"DMARC_AGGREGATE_REPORT"
"THREAT_INTEL_SUBMISSION"
"SIMULATION_SUBMISSION"
"API"
"RETRO_SCAN"
delivery_status: Optional[List[Literal["delivered", "moved", "quarantined", 5 more]]]
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
edf_hash: Optional[str]
envelope_from: Optional[str]
envelope_to: Optional[List[str]]
final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings: Optional[List[Finding]]

Use the findings field from GET /investigate/{investigate_id}/detections instead.

Deprecated, use the findings field from GET /investigate/{investigate_id}/detections instead. End of life: November 1, 2026. Detection findings for this message.

attachment: Optional[str]
detail: Optional[str]
detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field: Optional[str]
name: Optional[str]
portion: Optional[str]
reason: Optional[str]
score: Optional[float]
formatdouble
value: Optional[str]
from_: Optional[str]
from_name: Optional[str]
htmltext_structure_hash: Optional[str]
message_id: Optional[str]
post_delivery_operations: Optional[List[Literal["PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE"]]]

Post-delivery operations performed on this message.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound: Optional[str]
replyto: Optional[str]
scanned_at: Optional[datetime]

When the message was scanned (UTC).

formatdate-time
sent_at: Optional[datetime]

When the message was sent (UTC).

formatdate-time
sent_date: Optional[str]
smtp_helo_server_ip: Optional[str]
smtp_previous_hop_ip: Optional[str]
subject: Optional[str]
threat_categories: Optional[List[str]]
to: Optional[List[str]]
to_name: Optional[List[str]]
validation: Optional[Validation]
comment: Optional[str]
dkim: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
x_originating_ip: Optional[str]
class InvestigateGetResponse: …
id: str

Unique identifier for a message retrieved from investigation.

Deprecatedaction_log: List[ActionLog]

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

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

completed_at: datetime

Timestamp when action completed.

formatdate-time
operation: Literal["MOVE", "RELEASE", "RECLASSIFY", 3 more]

Type of action performed.

One of the following:
"MOVE"
"RELEASE"
"RECLASSIFY"
"SUBMISSION"
"QUARANTINE_RELEASE"
"PREVIEW"
Deprecatedcompleted_timestamp: Optional[str]

Use completed_at instead.

Deprecated, use completed_at instead. End of life: November 1, 2026.

properties: Optional[ActionLogProperties]

Additional properties for the action.

folder: Optional[str]

Target folder for move operations.

requested_by: Optional[str]

User who requested the action.

status: Optional[str]

Status of the action.

client_recipients: List[str]
detection_reasons: List[str]
is_phish_submission: bool
is_quarantined: bool
postfix_id: str

The identifier of the message.

properties: Properties

Message processing properties.

allowlisted_pattern: Optional[str]

Pattern that allowlisted this message.

allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]

Type of allowlist pattern.

One of the following:
"quarantine_release"
"acceptable_sender"
"allowed_sender"
"allowed_recipient"
"domain_similarity"
"domain_recency"
"managed_acceptable_sender"
"outbound_ndr"
blocklisted_message: Optional[bool]

Whether message was blocklisted.

blocklisted_pattern: Optional[str]

Pattern that blocklisted this message.

whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]

Legacy field for allowlist pattern type.

One of the following:
"quarantine_release"
"acceptable_sender"
"allowed_sender"
"allowed_recipient"
"domain_similarity"
"domain_recency"
"managed_acceptable_sender"
"outbound_ndr"
Deprecatedts: str

Use scanned_at instead.

Deprecated, use scanned_at instead. End of life: November 1, 2026.

alert_id: Optional[str]
delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 8 more]]
One of the following:
"DIRECT"
"BCC"
"JOURNAL"
"REVIEW_SUBMISSION"
"DMARC_UNVERIFIED"
"DMARC_FAILURE_REPORT"
"DMARC_AGGREGATE_REPORT"
"THREAT_INTEL_SUBMISSION"
"SIMULATION_SUBMISSION"
"API"
"RETRO_SCAN"
delivery_status: Optional[List[Literal["delivered", "moved", "quarantined", 5 more]]]
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
edf_hash: Optional[str]
envelope_from: Optional[str]
envelope_to: Optional[List[str]]
final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings: Optional[List[Finding]]

Use the findings field from GET /investigate/{investigate_id}/detections instead.

Deprecated, use the findings field from GET /investigate/{investigate_id}/detections instead. End of life: November 1, 2026. Detection findings for this message.

attachment: Optional[str]
detail: Optional[str]
detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field: Optional[str]
name: Optional[str]
portion: Optional[str]
reason: Optional[str]
score: Optional[float]
formatdouble
value: Optional[str]
from_: Optional[str]
from_name: Optional[str]
htmltext_structure_hash: Optional[str]
message_id: Optional[str]
post_delivery_operations: Optional[List[Literal["PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE"]]]

Post-delivery operations performed on this message.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound: Optional[str]
replyto: Optional[str]
scanned_at: Optional[datetime]

When the message was scanned (UTC).

formatdate-time
sent_at: Optional[datetime]

When the message was sent (UTC).

formatdate-time
sent_date: Optional[str]
smtp_helo_server_ip: Optional[str]
smtp_previous_hop_ip: Optional[str]
subject: Optional[str]
threat_categories: Optional[List[str]]
to: Optional[List[str]]
to_name: Optional[List[str]]
validation: Optional[Validation]
comment: Optional[str]
dkim: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
x_originating_ip: Optional[str]

InvestigateDetections

Get message detection details
email_security.investigate.detections.get(strinvestigate_id, DetectionGetParams**kwargs) -> DetectionGetResponse
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/detections
ModelsExpand Collapse
class DetectionGetResponse: …
action: str
attachments: List[Attachment]
size: int

Size of the attachment in bytes.

minimum0
content_type: Optional[str]

MIME type of the attachment.

detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

Detection result for this attachment.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
encrypted: Optional[bool]

Whether the attachment is encrypted.

filename: Optional[str]

Name of the attached file.

md5: Optional[str]

MD5 hash of the attachment.

name: Optional[str]

Attachment name (alternative to filename).

sha1: Optional[str]

SHA1 hash of the attachment.

sha256: Optional[str]

SHA256 hash of the attachment.

findings: Optional[List[Finding]]
attachment: Optional[str]
detail: Optional[str]
detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

Detection result associated with this finding.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field: Optional[str]
name: Optional[str]
portion: Optional[str]
reason: Optional[str]
score: Optional[float]
formatdouble
value: Optional[str]
headers: List[Header]
name: str
value: str
text: Optional[str]
sender_info: SenderInfo
as_name: Optional[str]

The name of the autonomous system.

as_number: Optional[int]

The number of the autonomous system.

geo: Optional[str]
ip: Optional[str]
pld: Optional[str]
threat_categories: List[ThreatCategory]
id: Optional[int]
description: Optional[str]
name: Optional[str]
validation: Validation
comment: Optional[str]
dkim: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"

InvestigatePreview

Get preview for a detection
email_security.investigate.preview.get(strinvestigate_id, PreviewGetParams**kwargs) -> PreviewGetResponse
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/preview
Generate preview for a non-detection message
email_security.investigate.preview.create(PreviewCreateParams**kwargs) -> PreviewCreateResponse
POST/accounts/{account_id}/email-security/investigate/preview
ModelsExpand Collapse
class PreviewGetResponse: …
screenshot: str

A base64 encoded PNG image of the email.

class PreviewCreateResponse: …
screenshot: str

A base64 encoded PNG image of the email.

InvestigateRaw

Get raw email content
email_security.investigate.raw.get(strinvestigate_id, RawGetParams**kwargs) -> RawGetResponse
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/raw
ModelsExpand Collapse
class RawGetResponse: …
raw: str

A UTF-8 encoded eml file of the email.

InvestigateTrace

Get email trace
email_security.investigate.trace.get(strinvestigate_id, TraceGetParams**kwargs) -> TraceGetResponse
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/trace
ModelsExpand Collapse
class TraceGetResponse: …
inbound: Inbound
lines: Optional[List[InboundLine]]
lineno: Optional[int]

Line number in the trace log.

logged_at: Optional[datetime]
formatdate-time
message: Optional[str]
Deprecatedts: Optional[str]

Use logged_at instead.

Deprecated, use logged_at instead. End of life: November 1, 2026.

pending: Optional[bool]
outbound: Outbound
lines: Optional[List[OutboundLine]]
lineno: Optional[int]

Line number in the trace log.

logged_at: Optional[datetime]
formatdate-time
message: Optional[str]
Deprecatedts: Optional[str]

Use logged_at instead.

Deprecated, use logged_at instead. End of life: November 1, 2026.

pending: Optional[bool]

InvestigateMove

Move a message
email_security.investigate.move.create(strinvestigate_id, MoveCreateParams**kwargs) -> SyncSinglePage[MoveCreateResponse]
POST/accounts/{account_id}/email-security/investigate/{investigate_id}/move
Move messages
email_security.investigate.move.bulk(MoveBulkParams**kwargs) -> SyncSinglePage[MoveBulkResponse]
POST/accounts/{account_id}/email-security/investigate/move
ModelsExpand Collapse
class MoveCreateResponse: …
success: bool

Whether the operation succeeded.

completed_at: Optional[datetime]

When the move operation completed (UTC).

formatdate-time
Deprecatedcompleted_timestamp: Optional[datetime]

Use completed_at instead.

Deprecated, use completed_at instead. End of life: November 1, 2026.

formatdate-time
destination: Optional[str]

Destination folder for the message.

Deprecateditem_count: Optional[int]

This field is deprecated.

Number of items moved. End of life: November 1, 2026.

message_id: Optional[str]

Message identifier.

operation: Optional[str]

Type of operation performed.

recipient: Optional[str]

Recipient email address.

status: Optional[str]

Operation status.

class MoveBulkResponse: …
success: bool

Whether the operation succeeded.

completed_at: Optional[datetime]

When the move operation completed (UTC).

formatdate-time
Deprecatedcompleted_timestamp: Optional[datetime]

Use completed_at instead.

Deprecated, use completed_at instead. End of life: November 1, 2026.

formatdate-time
destination: Optional[str]

Destination folder for the message.

Deprecateditem_count: Optional[int]

This field is deprecated.

Number of items moved. End of life: November 1, 2026.

message_id: Optional[str]

Message identifier.

operation: Optional[str]

Type of operation performed.

recipient: Optional[str]

Recipient email address.

status: Optional[str]

Operation status.

InvestigateReclassify

Change email classification
Deprecated
email_security.investigate.reclassify.create(strinvestigate_id, ReclassifyCreateParams**kwargs) -> object
POST/accounts/{account_id}/email-security/investigate/{investigate_id}/reclassify

InvestigateRelease

Release messages from quarantine
email_security.investigate.release.bulk(ReleaseBulkParams**kwargs) -> SyncSinglePage[ReleaseBulkResponse]
POST/accounts/{account_id}/email-security/investigate/release
ModelsExpand Collapse
class ReleaseBulkResponse: …
id: str

Unique identifier for a message retrieved from investigation.

delivered: Optional[List[str]]
failed: Optional[List[str]]
Deprecatedpostfix_id: Optional[str]

Use id instead.

Deprecated, use id instead. End of life: November 1, 2026.

undelivered: Optional[List[str]]

InvestigateBulk

List bulk action jobs
email_security.investigate.bulk.list(BulkListParams**kwargs) -> SyncV4PagePaginationArray[BulkListResponse]
GET/accounts/{account_id}/email-security/investigate/bulk
Create a bulk action job
email_security.investigate.bulk.create(BulkCreateParams**kwargs) -> BulkCreateResponse
POST/accounts/{account_id}/email-security/investigate/bulk
Get bulk action job details
email_security.investigate.bulk.get(strjob_id, BulkGetParams**kwargs) -> BulkGetResponse
GET/accounts/{account_id}/email-security/investigate/bulk/{job_id}
Delete a bulk action job
email_security.investigate.bulk.delete(strjob_id, BulkDeleteParams**kwargs) -> BulkDeleteResponse
DELETE/accounts/{account_id}/email-security/investigate/bulk/{job_id}
ModelsExpand Collapse
class BulkListResponse: …
action_params: ActionParams
One of the following:
class ActionParamsMove: …
destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: Literal["MOVE"]
Deprecatedexpected_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

This field is nonfunctional.

Nonfunctional field. End of life: December 1, 2026.

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_cancelled: int

Messages that were cancelled: rows cancelled via the API before being claimed, and rows whose in-flight attempt ended when the job reached a terminal state. Together the counters satisfy total_messages_discovered = messages_pending + messages_successful + messages_failed + messages_skipped + messages_cancelled.

messages_failed: int
messages_pending: int
messages_skipped: int

Messages that discovery skipped (for example, phish submissions, which the job cannot action).

messages_successful: int
search_params: SearchParams
Deprecatedaction_log: Optional[bool]

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[str]

Alert ID of the detection to filter by.

delivery_status: Optional[Literal["delivered", "moved", "quarantined", 5 more]]

Delivery status to filter by.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
detections_only: Optional[bool]

Whether to include only detections in search results.

domain: Optional[str]

Match messages that mention this domain — sender domain, recipient domain, or a domain in a link.

end: Optional[datetime]

End of search date range.

formatdate-time
exact_subject: Optional[str]

Match messages whose subject line equals this value exactly.

final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

Dispositions to filter by.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action: Optional[Literal["PREVIEW", "QUARANTINE_RELEASED", "MOVED"]]

Message actions to filter by.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id: Optional[str]

Message-ID header value to filter by.

metric: Optional[str]

Metric name to filter the search by.

query: Optional[str]

Space-delimited search term. Case-insensitive.

recipient: Optional[str]

Match messages whose recipient is this email address or domain.

sender: Optional[str]

Match messages whose sender is this email address or domain.

smtp_helo_ip: Optional[str]

Matches messages whose SMTP HELO server IP address equals this value.

start: Optional[datetime]

Beginning of search date range.

formatdate-time
subject: Optional[str]

Match messages whose subject contains these keywords, in any order.

submissions: Optional[bool]

Whether to search reclassification submissions instead of original messages.

status: Literal["PENDING", "DISCOVERING", "PROCESSING", 3 more]

Status of a bulk action job.

One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
total_messages_discovered: int
comment: Optional[str]
completed_at: Optional[datetime]
formatdate-time
started_at: Optional[datetime]
formatdate-time
status_message: Optional[str]
class BulkCreateResponse: …
action_params: ActionParams
One of the following:
class ActionParamsMove: …
destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: Literal["MOVE"]
Deprecatedexpected_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

This field is nonfunctional.

Nonfunctional field. End of life: December 1, 2026.

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_cancelled: int

Messages that were cancelled: rows cancelled via the API before being claimed, and rows whose in-flight attempt ended when the job reached a terminal state. Together the counters satisfy total_messages_discovered = messages_pending + messages_successful + messages_failed + messages_skipped + messages_cancelled.

messages_failed: int
messages_pending: int
messages_skipped: int

Messages that discovery skipped (for example, phish submissions, which the job cannot action).

messages_successful: int
search_params: SearchParams
Deprecatedaction_log: Optional[bool]

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[str]

Alert ID of the detection to filter by.

delivery_status: Optional[Literal["delivered", "moved", "quarantined", 5 more]]

Delivery status to filter by.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
detections_only: Optional[bool]

Whether to include only detections in search results.

domain: Optional[str]

Match messages that mention this domain — sender domain, recipient domain, or a domain in a link.

end: Optional[datetime]

End of search date range.

formatdate-time
exact_subject: Optional[str]

Match messages whose subject line equals this value exactly.

final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

Dispositions to filter by.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action: Optional[Literal["PREVIEW", "QUARANTINE_RELEASED", "MOVED"]]

Message actions to filter by.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id: Optional[str]

Message-ID header value to filter by.

metric: Optional[str]

Metric name to filter the search by.

query: Optional[str]

Space-delimited search term. Case-insensitive.

recipient: Optional[str]

Match messages whose recipient is this email address or domain.

sender: Optional[str]

Match messages whose sender is this email address or domain.

smtp_helo_ip: Optional[str]

Matches messages whose SMTP HELO server IP address equals this value.

start: Optional[datetime]

Beginning of search date range.

formatdate-time
subject: Optional[str]

Match messages whose subject contains these keywords, in any order.

submissions: Optional[bool]

Whether to search reclassification submissions instead of original messages.

status: Literal["PENDING", "DISCOVERING", "PROCESSING", 3 more]

Status of a bulk action job.

One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
total_messages_discovered: int
comment: Optional[str]
completed_at: Optional[datetime]
formatdate-time
started_at: Optional[datetime]
formatdate-time
status_message: Optional[str]
class BulkGetResponse: …
action_params: ActionParams
One of the following:
class ActionParamsMove: …
destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: Literal["MOVE"]
Deprecatedexpected_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

This field is nonfunctional.

Nonfunctional field. End of life: December 1, 2026.

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_cancelled: int

Messages that were cancelled: rows cancelled via the API before being claimed, and rows whose in-flight attempt ended when the job reached a terminal state. Together the counters satisfy total_messages_discovered = messages_pending + messages_successful + messages_failed + messages_skipped + messages_cancelled.

messages_failed: int
messages_pending: int
messages_skipped: int

Messages that discovery skipped (for example, phish submissions, which the job cannot action).

messages_successful: int
search_params: SearchParams
Deprecatedaction_log: Optional[bool]

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[str]

Alert ID of the detection to filter by.

delivery_status: Optional[Literal["delivered", "moved", "quarantined", 5 more]]

Delivery status to filter by.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
detections_only: Optional[bool]

Whether to include only detections in search results.

domain: Optional[str]

Match messages that mention this domain — sender domain, recipient domain, or a domain in a link.

end: Optional[datetime]

End of search date range.

formatdate-time
exact_subject: Optional[str]

Match messages whose subject line equals this value exactly.

final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

Dispositions to filter by.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action: Optional[Literal["PREVIEW", "QUARANTINE_RELEASED", "MOVED"]]

Message actions to filter by.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id: Optional[str]

Message-ID header value to filter by.

metric: Optional[str]

Metric name to filter the search by.

query: Optional[str]

Space-delimited search term. Case-insensitive.

recipient: Optional[str]

Match messages whose recipient is this email address or domain.

sender: Optional[str]

Match messages whose sender is this email address or domain.

smtp_helo_ip: Optional[str]

Matches messages whose SMTP HELO server IP address equals this value.

start: Optional[datetime]

Beginning of search date range.

formatdate-time
subject: Optional[str]

Match messages whose subject contains these keywords, in any order.

submissions: Optional[bool]

Whether to search reclassification submissions instead of original messages.

status: Literal["PENDING", "DISCOVERING", "PROCESSING", 3 more]

Status of a bulk action job.

One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
total_messages_discovered: int
comment: Optional[str]
completed_at: Optional[datetime]
formatdate-time
started_at: Optional[datetime]
formatdate-time
status_message: Optional[str]
class BulkDeleteResponse: …
id: str
formatuuid

InvestigateBulkCancel

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
ModelsExpand Collapse
class CancelCreateResponse: …
action_params: ActionParams
One of the following:
class ActionParamsMove: …
destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: Literal["MOVE"]
Deprecatedexpected_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

This field is nonfunctional.

Nonfunctional field. End of life: December 1, 2026.

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_cancelled: int

Messages that were cancelled: rows cancelled via the API before being claimed, and rows whose in-flight attempt ended when the job reached a terminal state. Together the counters satisfy total_messages_discovered = messages_pending + messages_successful + messages_failed + messages_skipped + messages_cancelled.

messages_failed: int
messages_pending: int
messages_skipped: int

Messages that discovery skipped (for example, phish submissions, which the job cannot action).

messages_successful: int
search_params: SearchParams
Deprecatedaction_log: Optional[bool]

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[str]

Alert ID of the detection to filter by.

delivery_status: Optional[Literal["delivered", "moved", "quarantined", 5 more]]

Delivery status to filter by.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
detections_only: Optional[bool]

Whether to include only detections in search results.

domain: Optional[str]

Match messages that mention this domain — sender domain, recipient domain, or a domain in a link.

end: Optional[datetime]

End of search date range.

formatdate-time
exact_subject: Optional[str]

Match messages whose subject line equals this value exactly.

final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

Dispositions to filter by.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action: Optional[Literal["PREVIEW", "QUARANTINE_RELEASED", "MOVED"]]

Message actions to filter by.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id: Optional[str]

Message-ID header value to filter by.

metric: Optional[str]

Metric name to filter the search by.

query: Optional[str]

Space-delimited search term. Case-insensitive.

recipient: Optional[str]

Match messages whose recipient is this email address or domain.

sender: Optional[str]

Match messages whose sender is this email address or domain.

smtp_helo_ip: Optional[str]

Matches messages whose SMTP HELO server IP address equals this value.

start: Optional[datetime]

Beginning of search date range.

formatdate-time
subject: Optional[str]

Match messages whose subject contains these keywords, in any order.

submissions: Optional[bool]

Whether to search reclassification submissions instead of original messages.

status: Literal["PENDING", "DISCOVERING", "PROCESSING", 3 more]

Status of a bulk action job.

One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
total_messages_discovered: int
comment: Optional[str]
completed_at: Optional[datetime]
formatdate-time
started_at: Optional[datetime]
formatdate-time
status_message: Optional[str]

InvestigateBulkMessages

List messages for a bulk action job
email_security.investigate.bulk.messages.list(strjob_id, MessageListParams**kwargs) -> SyncV4PagePaginationArray[MessageListResponse]
GET/accounts/{account_id}/email-security/investigate/bulk/{job_id}/messages
ModelsExpand Collapse
class MessageListResponse: …
action_params: ActionParams
One of the following:
class ActionParamsMove: …
client_recipient: str
destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: Literal["MOVE"]
Deprecatedexpected_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

This field is nonfunctional.

Nonfunctional field. End of life: December 1, 2026.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
class ActionParamsRelease: …
client_recipient: str
type: Literal["RELEASE"]
action_type: Literal["MOVE", "RELEASE"]
One of the following:
"MOVE"
"RELEASE"
created_at: datetime
formatdate-time
message_id: str
formatuuid
postfix_id: str
retry_count: int
status: Literal["PENDING", "PROCESSING", "COMPLETED", 3 more]

Status of a message within a bulk action job.

One of the following:
"PENDING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
"SKIPPED"
alert_id: Optional[str]
email_message_id: Optional[str]
message: Optional[Message]
id: str

Unique identifier for a message retrieved from investigation.

Deprecatedaction_log: List[MessageActionLog]

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

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

completed_at: datetime

Timestamp when action completed.

formatdate-time
operation: Literal["MOVE", "RELEASE", "RECLASSIFY", 3 more]

Type of action performed.

One of the following:
"MOVE"
"RELEASE"
"RECLASSIFY"
"SUBMISSION"
"QUARANTINE_RELEASE"
"PREVIEW"
Deprecatedcompleted_timestamp: Optional[str]

Use completed_at instead.

Deprecated, use completed_at instead. End of life: November 1, 2026.

properties: Optional[MessageActionLogProperties]

Additional properties for the action.

folder: Optional[str]

Target folder for move operations.

requested_by: Optional[str]

User who requested the action.

status: Optional[str]

Status of the action.

client_recipients: List[str]
detection_reasons: List[str]
is_phish_submission: bool
is_quarantined: bool
postfix_id: str

The identifier of the message.

properties: MessageProperties

Message processing properties.

allowlisted_pattern: Optional[str]

Pattern that allowlisted this message.

allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]

Type of allowlist pattern.

One of the following:
"quarantine_release"
"acceptable_sender"
"allowed_sender"
"allowed_recipient"
"domain_similarity"
"domain_recency"
"managed_acceptable_sender"
"outbound_ndr"
blocklisted_message: Optional[bool]

Whether message was blocklisted.

blocklisted_pattern: Optional[str]

Pattern that blocklisted this message.

whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]

Legacy field for allowlist pattern type.

One of the following:
"quarantine_release"
"acceptable_sender"
"allowed_sender"
"allowed_recipient"
"domain_similarity"
"domain_recency"
"managed_acceptable_sender"
"outbound_ndr"
Deprecatedts: str

Use scanned_at instead.

Deprecated, use scanned_at instead. End of life: November 1, 2026.

alert_id: Optional[str]
delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 8 more]]
One of the following:
"DIRECT"
"BCC"
"JOURNAL"
"REVIEW_SUBMISSION"
"DMARC_UNVERIFIED"
"DMARC_FAILURE_REPORT"
"DMARC_AGGREGATE_REPORT"
"THREAT_INTEL_SUBMISSION"
"SIMULATION_SUBMISSION"
"API"
"RETRO_SCAN"
delivery_status: Optional[List[Literal["delivered", "moved", "quarantined", 5 more]]]
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
edf_hash: Optional[str]
envelope_from: Optional[str]
envelope_to: Optional[List[str]]
final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings: Optional[List[MessageFinding]]

Use the findings field from GET /investigate/{investigate_id}/detections instead.

Deprecated, use the findings field from GET /investigate/{investigate_id}/detections instead. End of life: November 1, 2026. Detection findings for this message.

attachment: Optional[str]
detail: Optional[str]
detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field: Optional[str]
name: Optional[str]
portion: Optional[str]
reason: Optional[str]
score: Optional[float]
formatdouble
value: Optional[str]
from_: Optional[str]
from_name: Optional[str]
htmltext_structure_hash: Optional[str]
message_id: Optional[str]
post_delivery_operations: Optional[List[Literal["PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE"]]]

Post-delivery operations performed on this message.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound: Optional[str]
replyto: Optional[str]
scanned_at: Optional[datetime]

When the message was scanned (UTC).

formatdate-time
sent_at: Optional[datetime]

When the message was sent (UTC).

formatdate-time
sent_date: Optional[str]
smtp_helo_server_ip: Optional[str]
smtp_previous_hop_ip: Optional[str]
subject: Optional[str]
threat_categories: Optional[List[str]]
to: Optional[List[str]]
to_name: Optional[List[str]]
validation: Optional[MessageValidation]
comment: Optional[str]
dkim: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
x_originating_ip: Optional[str]
processed_at: Optional[datetime]
formatdate-time
retry_after: Optional[datetime]

When to retry the action if it failed.

formatdate-time
status_message: Optional[str]