Skip to content
Cloudflare API
Start here
API Reference
Email Security

Investigate

Search email messages
client.emailSecurity.investigate.list(InvestigateListParams { account_id, action_log, alert_id, 15 more } params, RequestOptionsoptions?): V4PagePaginationArray<InvestigateListResponse { id, action_log, client_recipients, 29 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, 29 more }
GET/accounts/{account_id}/email-security/investigate/{investigate_id}
ModelsExpand Collapse
InvestigateListResponse { id, action_log, client_recipients, 29 more }
id: string

Unique identifier for a message retrieved from investigation

Deprecatedaction_log: Array<ActionLog>

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

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

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

alert_id?: string | null
delivery_mode?: "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?: Array<"delivered" | "moved" | "quarantined" | 4 more> | null
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
edf_hash?: string | null
envelope_from?: string | null
envelope_to?: Array<string> | null
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings?: Array<Finding> | null

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
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
subject?: string | null
threat_categories?: Array<string> | null
to?: Array<string> | null
to_name?: Array<string> | null
validation?: Validation { comment, dkim, dmarc, spf }
comment?: string | null
dkim?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
InvestigateGetResponse { id, action_log, client_recipients, 29 more }
id: string

Unique identifier for a message retrieved from investigation

Deprecatedaction_log: Array<ActionLog>

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

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

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

alert_id?: string | null
delivery_mode?: "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?: Array<"delivered" | "moved" | "quarantined" | 4 more> | null
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
edf_hash?: string | null
envelope_from?: string | null
envelope_to?: Array<string> | null
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings?: Array<Finding> | null

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
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
subject?: string | null
threat_categories?: Array<string> | null
to?: Array<string> | null
to_name?: Array<string> | null
validation?: Validation { comment, dkim, dmarc, spf }
comment?: string | null
dkim?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"

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
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
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"

InvestigatePreview

Get email preview
client.emailSecurity.investigate.preview.get(stringinvestigateId, PreviewGetParams { account_id } params, RequestOptionsoptions?): PreviewGetResponse { screenshot }
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/preview
Preview for non-detection messages
client.emailSecurity.investigate.preview.create(PreviewCreateParams { account_id, postfix_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

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

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 } params, RequestOptionsoptions?): SinglePage<MoveCreateResponse { success, completed_at, completed_timestamp, 6 more } >
POST/accounts/{account_id}/email-security/investigate/{investigate_id}/move
Move multiple messages
client.emailSecurity.investigate.move.bulk(MoveBulkParams { account_id, destination, ids, postfix_ids } 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

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

formatdate-time
destination?: string | null

Destination folder for the message

Deprecateditem_count?: number

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

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

formatdate-time
destination?: string | null

Destination folder for the message

Deprecateditem_count?: number

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
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, body } 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

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

undelivered?: Array<string> | null