Skip to content
Cloudflare API
Start here
API Reference
Email Security

Investigate

Search email messages
client.emailSecurity.investigate.list(InvestigateListParams { account_id, alert_id, cursor, 16 more } params, RequestOptionsoptions?): V4PagePaginationArray<InvestigateListResponse { id, action_log, client_recipients, 32 more } >
GET/accounts/{account_id}/email-security/investigate
Get message details
client.emailSecurity.investigate.get(stringinvestigateID, InvestigateGetParams { account_id, submission } params, RequestOptionsoptions?): InvestigateGetResponse { id, action_log, client_recipients, 32 more }
GET/accounts/{account_id}/email-security/investigate/{investigate_id}
ModelsExpand Collapse
InvestigateListResponse { id, action_log, client_recipients, 32 more }
id: string

Unique identifier for a message retrieved from investigation.

Deprecatedaction_log: Array<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: string

Timestamp when action completed.

formatdate-time
operation: "MOVE" | "RELEASE" | "RECLASSIFY" | 3 more

Type of action performed.

One of the following:
"MOVE"
"RELEASE"
"RECLASSIFY"
"SUBMISSION"
"QUARANTINE_RELEASE"
"PREVIEW"
Deprecatedcompleted_timestamp?: string

Use completed_at instead.

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

properties?: Properties { folder, requested_by }

Additional properties for the action.

folder?: string

Target folder for move operations.

requested_by?: string

User who requested the action.

status?: string | null

Status of the action.

client_recipients: Array<string>
detection_reasons: Array<string>
is_phish_submission: boolean
is_quarantined: boolean
postfix_id: string

The identifier of the message.

properties: Properties { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }

Message processing properties.

allowlisted_pattern?: string | null

Pattern that allowlisted this message.

allowlisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 5 more | null

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?: boolean | null

Whether message was blocklisted.

blocklisted_pattern?: string | null

Pattern that blocklisted this message.

whitelisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 5 more | null

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: string

Use scanned_at instead.

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

alert_id?: string | null
delivery_mode?: "DIRECT" | "BCC" | "JOURNAL" | 8 more | null
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?: Array<"delivered" | "moved" | "quarantined" | 5 more> | null
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
edf_hash?: string | null
envelope_from?: string | null
envelope_to?: Array<string> | null
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings?: Array<Finding> | null

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?: string | null
detail?: string | null
detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field?: string | null
name?: string | null
portion?: string | null
reason?: string | null
score?: number | null
formatdouble
value?: string | null
from?: string | null
from_name?: string | null
htmltext_structure_hash?: string | null
message_id?: string | null
post_delivery_operations?: Array<"PREVIEW" | "QUARANTINE_RELEASE" | "SUBMISSION" | "MOVE"> | null

Post-delivery operations performed on this message.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound?: string | null
replyto?: string | null
scanned_at?: string | null

When the message was scanned (UTC).

formatdate-time
sent_at?: string | null

When the message was sent (UTC).

formatdate-time
sent_date?: string | null
smtp_helo_server_ip?: string | null
smtp_previous_hop_ip?: string | null
subject?: string | null
threat_categories?: Array<string> | null
to?: Array<string> | null
to_name?: Array<string> | null
validation?: Validation | null
comment?: string | null
dkim?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
x_originating_ip?: string | null
InvestigateGetResponse { id, action_log, client_recipients, 32 more }
id: string

Unique identifier for a message retrieved from investigation.

Deprecatedaction_log: Array<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: string

Timestamp when action completed.

formatdate-time
operation: "MOVE" | "RELEASE" | "RECLASSIFY" | 3 more

Type of action performed.

One of the following:
"MOVE"
"RELEASE"
"RECLASSIFY"
"SUBMISSION"
"QUARANTINE_RELEASE"
"PREVIEW"
Deprecatedcompleted_timestamp?: string

Use completed_at instead.

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

properties?: Properties { folder, requested_by }

Additional properties for the action.

folder?: string

Target folder for move operations.

requested_by?: string

User who requested the action.

status?: string | null

Status of the action.

client_recipients: Array<string>
detection_reasons: Array<string>
is_phish_submission: boolean
is_quarantined: boolean
postfix_id: string

The identifier of the message.

properties: Properties { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }

Message processing properties.

allowlisted_pattern?: string | null

Pattern that allowlisted this message.

allowlisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 5 more | null

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?: boolean | null

Whether message was blocklisted.

blocklisted_pattern?: string | null

Pattern that blocklisted this message.

whitelisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 5 more | null

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: string

Use scanned_at instead.

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

alert_id?: string | null
delivery_mode?: "DIRECT" | "BCC" | "JOURNAL" | 8 more | null
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?: Array<"delivered" | "moved" | "quarantined" | 5 more> | null
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
edf_hash?: string | null
envelope_from?: string | null
envelope_to?: Array<string> | null
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings?: Array<Finding> | null

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?: string | null
detail?: string | null
detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field?: string | null
name?: string | null
portion?: string | null
reason?: string | null
score?: number | null
formatdouble
value?: string | null
from?: string | null
from_name?: string | null
htmltext_structure_hash?: string | null
message_id?: string | null
post_delivery_operations?: Array<"PREVIEW" | "QUARANTINE_RELEASE" | "SUBMISSION" | "MOVE"> | null

Post-delivery operations performed on this message.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound?: string | null
replyto?: string | null
scanned_at?: string | null

When the message was scanned (UTC).

formatdate-time
sent_at?: string | null

When the message was sent (UTC).

formatdate-time
sent_date?: string | null
smtp_helo_server_ip?: string | null
smtp_previous_hop_ip?: string | null
subject?: string | null
threat_categories?: Array<string> | null
to?: Array<string> | null
to_name?: Array<string> | null
validation?: Validation | null
comment?: string | null
dkim?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
x_originating_ip?: string | null

InvestigateDetections

Get message detection details
client.emailSecurity.investigate.detections.get(stringinvestigateID, DetectionGetParams { account_id } params, RequestOptionsoptions?): DetectionGetResponse { action, attachments, findings, 6 more }
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/detections
ModelsExpand Collapse
DetectionGetResponse { action, attachments, findings, 6 more }
action: string
attachments: Array<Attachment>
size: number

Size of the attachment in bytes.

minimum0
content_type?: string | null

MIME type of the attachment.

detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

Detection result for this attachment.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
encrypted?: boolean | null

Whether the attachment is encrypted.

filename?: string | null

Name of the attached file.

md5?: string | null

MD5 hash of the attachment.

name?: string | null

Attachment name (alternative to filename).

sha1?: string | null

SHA1 hash of the attachment.

sha256?: string | null

SHA256 hash of the attachment.

findings: Array<Finding> | null
attachment?: string | null
detail?: string | null
detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

Detection result associated with this finding.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field?: string | null
name?: string | null
portion?: string | null
reason?: string | null
score?: number | null
formatdouble
value?: string | null
headers: Array<Header>
name: string
value: string
text?: string | null
sender_info: SenderInfo { as_name, as_number, geo, 2 more }
as_name?: string | null

The name of the autonomous system.

as_number?: number | null

The number of the autonomous system.

geo?: string | null
ip?: string | null
pld?: string | null
threat_categories: Array<ThreatCategory>
id?: number
description?: string | null
name?: string | null
validation: Validation { comment, dkim, dmarc, spf }
comment?: string | null
dkim?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

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
client.emailSecurity.investigate.preview.get(stringinvestigateID, PreviewGetParams { account_id } params, RequestOptionsoptions?): PreviewGetResponse { screenshot }
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/preview
Generate preview for a non-detection message
client.emailSecurity.investigate.preview.create(PreviewCreateParams { account_id, id } params, RequestOptionsoptions?): PreviewCreateResponse { screenshot }
POST/accounts/{account_id}/email-security/investigate/preview
ModelsExpand Collapse
PreviewGetResponse { screenshot }
screenshot: string

A base64 encoded PNG image of the email.

PreviewCreateResponse { screenshot }
screenshot: string

A base64 encoded PNG image of the email.

InvestigateRaw

Get raw email content
client.emailSecurity.investigate.raw.get(stringinvestigateID, RawGetParams { account_id } params, RequestOptionsoptions?): RawGetResponse { raw }
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/raw
ModelsExpand Collapse
RawGetResponse { raw }
raw: string

A UTF-8 encoded eml file of the email.

InvestigateTrace

Get email trace
client.emailSecurity.investigate.trace.get(stringinvestigateID, TraceGetParams { account_id } params, RequestOptionsoptions?): TraceGetResponse { inbound, outbound }
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/trace
ModelsExpand Collapse
TraceGetResponse { inbound, outbound }
inbound: Inbound { lines, pending }
lines?: Array<Line> | null
lineno?: number

Line number in the trace log.

logged_at?: string | null
formatdate-time
message?: string
Deprecatedts?: string

Use logged_at instead.

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

pending?: boolean | null
outbound: Outbound { lines, pending }
lines?: Array<Line> | null
lineno?: number

Line number in the trace log.

logged_at?: string | null
formatdate-time
message?: string
Deprecatedts?: string

Use logged_at instead.

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

pending?: boolean | null

InvestigateMove

Move a message
client.emailSecurity.investigate.move.create(stringinvestigateID, MoveCreateParams { account_id, destination, expected_disposition } params, RequestOptionsoptions?): SinglePage<MoveCreateResponse { success, completed_at, completed_timestamp, 6 more } >
POST/accounts/{account_id}/email-security/investigate/{investigate_id}/move
Move messages
client.emailSecurity.investigate.move.bulk(MoveBulkParams { account_id, destination, ids, 2 more } params, RequestOptionsoptions?): SinglePage<MoveBulkResponse { success, completed_at, completed_timestamp, 6 more } >
POST/accounts/{account_id}/email-security/investigate/move
ModelsExpand Collapse
MoveCreateResponse { success, completed_at, completed_timestamp, 6 more }
success: boolean

Whether the operation succeeded.

completed_at?: string | null

When the move operation completed (UTC).

formatdate-time
Deprecatedcompleted_timestamp?: string

Use completed_at instead.

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

formatdate-time
destination?: string | null

Destination folder for the message.

Deprecateditem_count?: number

This field is deprecated.

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

message_id?: string | null

Message identifier.

operation?: string | null

Type of operation performed.

recipient?: string | null

Recipient email address.

status?: string | null

Operation status.

MoveBulkResponse { success, completed_at, completed_timestamp, 6 more }
success: boolean

Whether the operation succeeded.

completed_at?: string | null

When the move operation completed (UTC).

formatdate-time
Deprecatedcompleted_timestamp?: string

Use completed_at instead.

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

formatdate-time
destination?: string | null

Destination folder for the message.

Deprecateditem_count?: number

This field is deprecated.

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

message_id?: string | null

Message identifier.

operation?: string | null

Type of operation performed.

recipient?: string | null

Recipient email address.

status?: string | null

Operation status.

InvestigateReclassify

Change email classification
Deprecated
client.emailSecurity.investigate.reclassify.create(stringinvestigateID, ReclassifyCreateParams { account_id, expected_disposition, eml_content, escalated_submission_id } params, RequestOptionsoptions?): ReclassifyCreateResponse
POST/accounts/{account_id}/email-security/investigate/{investigate_id}/reclassify
ModelsExpand Collapse
ReclassifyCreateResponse = unknown

InvestigateRelease

Release messages from quarantine
client.emailSecurity.investigate.release.bulk(ReleaseBulkParams { account_id, ids } params, RequestOptionsoptions?): SinglePage<ReleaseBulkResponse { id, delivered, failed, 2 more } >
POST/accounts/{account_id}/email-security/investigate/release
ModelsExpand Collapse
ReleaseBulkResponse { id, delivered, failed, 2 more }
id: string

Unique identifier for a message retrieved from investigation.

delivered?: Array<string> | null
failed?: Array<string> | null
Deprecatedpostfix_id?: string

Use id instead.

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

undelivered?: Array<string> | null

InvestigateBulk

List bulk action jobs
client.emailSecurity.investigate.bulk.list(BulkListParams { account_id, action_type, page, 2 more } params, RequestOptionsoptions?): V4PagePaginationArray<BulkListResponse { action_params, action_type, created_at, 13 more } >
GET/accounts/{account_id}/email-security/investigate/bulk
Create a bulk action job
client.emailSecurity.investigate.bulk.create(BulkCreateParams { account_id, action, search_params, 3 more } params, RequestOptionsoptions?): BulkCreateResponse { action_params, action_type, created_at, 13 more }
POST/accounts/{account_id}/email-security/investigate/bulk
Get bulk action job details
client.emailSecurity.investigate.bulk.get(stringjobID, BulkGetParams { account_id } params, RequestOptionsoptions?): BulkGetResponse { action_params, action_type, created_at, 13 more }
GET/accounts/{account_id}/email-security/investigate/bulk/{job_id}
Delete a bulk action job
client.emailSecurity.investigate.bulk.delete(stringjobID, BulkDeleteParams { account_id } params, RequestOptionsoptions?): BulkDeleteResponse { id }
DELETE/accounts/{account_id}/email-security/investigate/bulk/{job_id}
ModelsExpand Collapse
BulkListResponse { action_params, action_type, created_at, 13 more }
action_params: Move { destination, type, expected_disposition } | Release { type }
One of the following:
Move { destination, type, expected_disposition }
destination: "Inbox" | "JunkEmail" | "DeletedItems" | 2 more

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
Deprecatedexpected_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

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"
Release { type }
type: "RELEASE"
action_type: "MOVE" | "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
job_id: string
formatuuid
messages_cancelled: number

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: number
messages_pending: number
messages_skipped: number

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

messages_successful: number
search_params: SearchParams { action_log, alert_id, delivery_status, 15 more }
Deprecatedaction_log?: 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?: string | null

Alert ID of the detection to filter by.

delivery_status?: "delivered" | "moved" | "quarantined" | 5 more | null

Delivery status to filter by.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
detections_only?: boolean

Whether to include only detections in search results.

domain?: string | null

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

end?: string

End of search date range.

formatdate-time
exact_subject?: string | null

Match messages whose subject line equals this value exactly.

final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

Dispositions to filter by.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action?: "PREVIEW" | "QUARANTINE_RELEASED" | "MOVED" | null

Message actions to filter by.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id?: string | null

Message-ID header value to filter by.

metric?: string | null

Metric name to filter the search by.

query?: string | null

Space-delimited search term. Case-insensitive.

recipient?: string | null

Match messages whose recipient is this email address or domain.

sender?: string | null

Match messages whose sender is this email address or domain.

smtp_helo_ip?: string | null

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

start?: string

Beginning of search date range.

formatdate-time
subject?: string | null

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

submissions?: boolean

Whether to search reclassification submissions instead of original messages.

status: "PENDING" | "DISCOVERING" | "PROCESSING" | 3 more

Status of a bulk action job.

One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
total_messages_discovered: number
comment?: string | null
completed_at?: string | null
formatdate-time
started_at?: string | null
formatdate-time
status_message?: string | null
BulkCreateResponse { action_params, action_type, created_at, 13 more }
action_params: Move { destination, type, expected_disposition } | Release { type }
One of the following:
Move { destination, type, expected_disposition }
destination: "Inbox" | "JunkEmail" | "DeletedItems" | 2 more

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
Deprecatedexpected_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

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"
Release { type }
type: "RELEASE"
action_type: "MOVE" | "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
job_id: string
formatuuid
messages_cancelled: number

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: number
messages_pending: number
messages_skipped: number

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

messages_successful: number
search_params: SearchParams { action_log, alert_id, delivery_status, 15 more }
Deprecatedaction_log?: 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?: string | null

Alert ID of the detection to filter by.

delivery_status?: "delivered" | "moved" | "quarantined" | 5 more | null

Delivery status to filter by.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
detections_only?: boolean

Whether to include only detections in search results.

domain?: string | null

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

end?: string

End of search date range.

formatdate-time
exact_subject?: string | null

Match messages whose subject line equals this value exactly.

final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

Dispositions to filter by.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action?: "PREVIEW" | "QUARANTINE_RELEASED" | "MOVED" | null

Message actions to filter by.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id?: string | null

Message-ID header value to filter by.

metric?: string | null

Metric name to filter the search by.

query?: string | null

Space-delimited search term. Case-insensitive.

recipient?: string | null

Match messages whose recipient is this email address or domain.

sender?: string | null

Match messages whose sender is this email address or domain.

smtp_helo_ip?: string | null

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

start?: string

Beginning of search date range.

formatdate-time
subject?: string | null

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

submissions?: boolean

Whether to search reclassification submissions instead of original messages.

status: "PENDING" | "DISCOVERING" | "PROCESSING" | 3 more

Status of a bulk action job.

One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
total_messages_discovered: number
comment?: string | null
completed_at?: string | null
formatdate-time
started_at?: string | null
formatdate-time
status_message?: string | null
BulkGetResponse { action_params, action_type, created_at, 13 more }
action_params: Move { destination, type, expected_disposition } | Release { type }
One of the following:
Move { destination, type, expected_disposition }
destination: "Inbox" | "JunkEmail" | "DeletedItems" | 2 more

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
Deprecatedexpected_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

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"
Release { type }
type: "RELEASE"
action_type: "MOVE" | "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
job_id: string
formatuuid
messages_cancelled: number

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: number
messages_pending: number
messages_skipped: number

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

messages_successful: number
search_params: SearchParams { action_log, alert_id, delivery_status, 15 more }
Deprecatedaction_log?: 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?: string | null

Alert ID of the detection to filter by.

delivery_status?: "delivered" | "moved" | "quarantined" | 5 more | null

Delivery status to filter by.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
detections_only?: boolean

Whether to include only detections in search results.

domain?: string | null

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

end?: string

End of search date range.

formatdate-time
exact_subject?: string | null

Match messages whose subject line equals this value exactly.

final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

Dispositions to filter by.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action?: "PREVIEW" | "QUARANTINE_RELEASED" | "MOVED" | null

Message actions to filter by.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id?: string | null

Message-ID header value to filter by.

metric?: string | null

Metric name to filter the search by.

query?: string | null

Space-delimited search term. Case-insensitive.

recipient?: string | null

Match messages whose recipient is this email address or domain.

sender?: string | null

Match messages whose sender is this email address or domain.

smtp_helo_ip?: string | null

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

start?: string

Beginning of search date range.

formatdate-time
subject?: string | null

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

submissions?: boolean

Whether to search reclassification submissions instead of original messages.

status: "PENDING" | "DISCOVERING" | "PROCESSING" | 3 more

Status of a bulk action job.

One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
total_messages_discovered: number
comment?: string | null
completed_at?: string | null
formatdate-time
started_at?: string | null
formatdate-time
status_message?: string | null
BulkDeleteResponse { id }
id: string
formatuuid

InvestigateBulkCancel

Cancel a bulk action job
client.emailSecurity.investigate.bulk.cancel.create(stringjobID, CancelCreateParams { account_id } params, RequestOptionsoptions?): CancelCreateResponse { action_params, action_type, created_at, 13 more }
POST/accounts/{account_id}/email-security/investigate/bulk/{job_id}/cancel
ModelsExpand Collapse
CancelCreateResponse { action_params, action_type, created_at, 13 more }
action_params: Move { destination, type, expected_disposition } | Release { type }
One of the following:
Move { destination, type, expected_disposition }
destination: "Inbox" | "JunkEmail" | "DeletedItems" | 2 more

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
Deprecatedexpected_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

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"
Release { type }
type: "RELEASE"
action_type: "MOVE" | "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
job_id: string
formatuuid
messages_cancelled: number

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: number
messages_pending: number
messages_skipped: number

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

messages_successful: number
search_params: SearchParams { action_log, alert_id, delivery_status, 15 more }
Deprecatedaction_log?: 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?: string | null

Alert ID of the detection to filter by.

delivery_status?: "delivered" | "moved" | "quarantined" | 5 more | null

Delivery status to filter by.

One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
detections_only?: boolean

Whether to include only detections in search results.

domain?: string | null

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

end?: string

End of search date range.

formatdate-time
exact_subject?: string | null

Match messages whose subject line equals this value exactly.

final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

Dispositions to filter by.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
message_action?: "PREVIEW" | "QUARANTINE_RELEASED" | "MOVED" | null

Message actions to filter by.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
message_id?: string | null

Message-ID header value to filter by.

metric?: string | null

Metric name to filter the search by.

query?: string | null

Space-delimited search term. Case-insensitive.

recipient?: string | null

Match messages whose recipient is this email address or domain.

sender?: string | null

Match messages whose sender is this email address or domain.

smtp_helo_ip?: string | null

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

start?: string

Beginning of search date range.

formatdate-time
subject?: string | null

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

submissions?: boolean

Whether to search reclassification submissions instead of original messages.

status: "PENDING" | "DISCOVERING" | "PROCESSING" | 3 more

Status of a bulk action job.

One of the following:
"PENDING"
"DISCOVERING"
"PROCESSING"
"COMPLETED"
"FAILED"
"CANCELLED"
total_messages_discovered: number
comment?: string | null
completed_at?: string | null
formatdate-time
started_at?: string | null
formatdate-time
status_message?: string | null

InvestigateBulkMessages

List messages for a bulk action job
client.emailSecurity.investigate.bulk.messages.list(stringjobID, MessageListParams { account_id, page, per_page, status } params, RequestOptionsoptions?): V4PagePaginationArray<MessageListResponse { action_params, action_type, created_at, 10 more } >
GET/accounts/{account_id}/email-security/investigate/bulk/{job_id}/messages
ModelsExpand Collapse
MessageListResponse { action_params, action_type, created_at, 10 more }
action_params: Move { client_recipient, destination, type, expected_disposition } | Release { client_recipient, type }
One of the following:
Move { client_recipient, destination, type, expected_disposition }
client_recipient: string
destination: "Inbox" | "JunkEmail" | "DeletedItems" | 2 more

The mailbox folder to move messages to.

One of the following:
"Inbox"
"JunkEmail"
"DeletedItems"
"RecoverableItemsDeletions"
"RecoverableItemsPurges"
type: "MOVE"
Deprecatedexpected_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

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"
Release { client_recipient, type }
client_recipient: string
type: "RELEASE"
action_type: "MOVE" | "RELEASE"
One of the following:
"MOVE"
"RELEASE"
created_at: string
formatdate-time
message_id: string
formatuuid
postfix_id: string
retry_count: number
status: "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?: string | null
email_message_id?: string | null
message?: Message { id, action_log, client_recipients, 32 more }
id: string

Unique identifier for a message retrieved from investigation.

Deprecatedaction_log: Array<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: string

Timestamp when action completed.

formatdate-time
operation: "MOVE" | "RELEASE" | "RECLASSIFY" | 3 more

Type of action performed.

One of the following:
"MOVE"
"RELEASE"
"RECLASSIFY"
"SUBMISSION"
"QUARANTINE_RELEASE"
"PREVIEW"
Deprecatedcompleted_timestamp?: string

Use completed_at instead.

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

properties?: Properties { folder, requested_by }

Additional properties for the action.

folder?: string

Target folder for move operations.

requested_by?: string

User who requested the action.

status?: string | null

Status of the action.

client_recipients: Array<string>
detection_reasons: Array<string>
is_phish_submission: boolean
is_quarantined: boolean
postfix_id: string

The identifier of the message.

properties: Properties { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }

Message processing properties.

allowlisted_pattern?: string | null

Pattern that allowlisted this message.

allowlisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 5 more | null

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?: boolean | null

Whether message was blocklisted.

blocklisted_pattern?: string | null

Pattern that blocklisted this message.

whitelisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 5 more | null

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: string

Use scanned_at instead.

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

alert_id?: string | null
delivery_mode?: "DIRECT" | "BCC" | "JOURNAL" | 8 more | null
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?: Array<"delivered" | "moved" | "quarantined" | 5 more> | null
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
"move_failed"
edf_hash?: string | null
envelope_from?: string | null
envelope_to?: Array<string> | null
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings?: Array<Finding> | null

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?: string | null
detail?: string | null
detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

The verdict Email Security assigns to a message.

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field?: string | null
name?: string | null
portion?: string | null
reason?: string | null
score?: number | null
formatdouble
value?: string | null
from?: string | null
from_name?: string | null
htmltext_structure_hash?: string | null
message_id?: string | null
post_delivery_operations?: Array<"PREVIEW" | "QUARANTINE_RELEASE" | "SUBMISSION" | "MOVE"> | null

Post-delivery operations performed on this message.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound?: string | null
replyto?: string | null
scanned_at?: string | null

When the message was scanned (UTC).

formatdate-time
sent_at?: string | null

When the message was sent (UTC).

formatdate-time
sent_date?: string | null
smtp_helo_server_ip?: string | null
smtp_previous_hop_ip?: string | null
subject?: string | null
threat_categories?: Array<string> | null
to?: Array<string> | null
to_name?: Array<string> | null
validation?: Validation | null
comment?: string | null
dkim?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
x_originating_ip?: string | null
processed_at?: string | null
formatdate-time
retry_after?: string | null

When to retry the action if it failed.

formatdate-time
status_message?: string | null