Skip to content
Cloudflare API
Start here
API Reference
Email Security

Investigate

Search email messages
GET/accounts/{account_id}/email-security/investigate
Get message details
GET/accounts/{account_id}/email-security/investigate/{postfix_id}
ModelsExpand Collapse
InvestigateListResponse object { id, action_log, client_recipients, 29 more }
id: string
Deprecatedaction_log: unknown

Deprecated: use /investigate/{id}/action_log instead.

client_recipients: array of string
detection_reasons: array of string
is_phish_submission: boolean
is_quarantined: boolean
postfix_id: string

The identifier of the message.

properties: object { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }
allowlisted_pattern: optional string
allowlisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more
One of the following:
"quarantine_release"
"acceptable_sender"
"allowed_sender"
"allowed_recipient"
"domain_similarity"
"domain_recency"
"managed_acceptable_sender"
"outbound_ndr"
blocklisted_message: optional boolean
blocklisted_pattern: optional string
whitelisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more
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

alert_id: optional string
delivery_mode: optional "DIRECT" or "BCC" or "JOURNAL" or 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 array of "delivered" or "moved" or "quarantined" or 4 more
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
edf_hash: optional string
envelope_from: optional string
envelope_to: optional array of string
final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings: optional array of object { attachment, detail, detection, 6 more }

Deprecated: use /investigate/{id}/detections instead.

attachment: optional string
detail: optional string
detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field: optional string
name: optional string
portion: optional string
reason: optional string
score: optional number
formatdouble
value: optional string
from: optional string
from_name: optional string
htmltext_structure_hash: optional string
message_id: optional string
post_delivery_operations: optional array of "PREVIEW" or "QUARANTINE_RELEASE" or "SUBMISSION" or "MOVE"
One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound: optional string
replyto: optional string
scanned_at: optional string
formatdate-time
sent_at: optional string
formatdate-time
Deprecatedsent_date: optional string

Deprecated, use sent_at instead

subject: optional string
threat_categories: optional array of string
to: optional array of string
to_name: optional array of string
validation: optional object { comment, dkim, dmarc, spf }
comment: optional string
dkim: optional "pass" or "neutral" or "fail" or 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc: optional "pass" or "neutral" or "fail" or 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf: optional "pass" or "neutral" or "fail" or 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
InvestigateGetResponse object { id, action_log, client_recipients, 29 more }
id: string
Deprecatedaction_log: unknown

Deprecated: use /investigate/{id}/action_log instead.

client_recipients: array of string
detection_reasons: array of string
is_phish_submission: boolean
is_quarantined: boolean
postfix_id: string

The identifier of the message.

properties: object { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }
allowlisted_pattern: optional string
allowlisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more
One of the following:
"quarantine_release"
"acceptable_sender"
"allowed_sender"
"allowed_recipient"
"domain_similarity"
"domain_recency"
"managed_acceptable_sender"
"outbound_ndr"
blocklisted_message: optional boolean
blocklisted_pattern: optional string
whitelisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more
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

alert_id: optional string
delivery_mode: optional "DIRECT" or "BCC" or "JOURNAL" or 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 array of "delivered" or "moved" or "quarantined" or 4 more
One of the following:
"delivered"
"moved"
"quarantined"
"rejected"
"deferred"
"bounced"
"queued"
edf_hash: optional string
envelope_from: optional string
envelope_to: optional array of string
final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
Deprecatedfindings: optional array of object { attachment, detail, detection, 6 more }

Deprecated: use /investigate/{id}/detections instead.

attachment: optional string
detail: optional string
detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field: optional string
name: optional string
portion: optional string
reason: optional string
score: optional number
formatdouble
value: optional string
from: optional string
from_name: optional string
htmltext_structure_hash: optional string
message_id: optional string
post_delivery_operations: optional array of "PREVIEW" or "QUARANTINE_RELEASE" or "SUBMISSION" or "MOVE"
One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound: optional string
replyto: optional string
scanned_at: optional string
formatdate-time
sent_at: optional string
formatdate-time
Deprecatedsent_date: optional string

Deprecated, use sent_at instead

subject: optional string
threat_categories: optional array of string
to: optional array of string
to_name: optional array of string
validation: optional object { comment, dkim, dmarc, spf }
comment: optional string
dkim: optional "pass" or "neutral" or "fail" or 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc: optional "pass" or "neutral" or "fail" or 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf: optional "pass" or "neutral" or "fail" or 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"

InvestigateDetections

Get message detection details
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/detections
ModelsExpand Collapse
DetectionGetResponse object { action, attachments, findings, 6 more }
action: string
attachments: array of object { size, content_type, detection, 2 more }
size: number
minimum0
content_type: optional string
detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
encrypted: optional boolean
name: optional string
findings: array of object { attachment, detail, detection, 6 more }
attachment: optional string
detail: optional string
detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field: optional string
name: optional string
portion: optional string
reason: optional string
score: optional number
formatdouble
value: optional string
headers: array of object { name, value }
name: string
value: string
text: optional string
sender_info: object { as_name, as_number, geo, 2 more }
as_name: optional string

The name of the autonomous system.

as_number: optional number

The number of the autonomous system.

formatint64
geo: optional string
ip: optional string
pld: optional string
threat_categories: array of object { id, description, name }
id: number
formatint64
description: optional string
name: optional string
validation: object { comment, dkim, dmarc, spf }
comment: optional string
dkim: optional "pass" or "neutral" or "fail" or 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc: optional "pass" or "neutral" or "fail" or 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf: optional "pass" or "neutral" or "fail" or 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"

InvestigatePreview

Get email preview
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/preview
Preview for non-detection messages
POST/accounts/{account_id}/email-security/investigate/preview
ModelsExpand Collapse
PreviewGetResponse object { screenshot }
screenshot: string

A base64 encoded PNG image of the email.

PreviewCreateResponse object { screenshot }
screenshot: string

A base64 encoded PNG image of the email.

InvestigateRaw

Get raw email content
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/raw
ModelsExpand Collapse
RawGetResponse object { raw }
raw: string

A UTF-8 encoded eml file of the email.

InvestigateTrace

Get email trace
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/trace
ModelsExpand Collapse
TraceGetResponse object { inbound, outbound }
inbound: object { lines, pending }
lines: optional array of object { lineno, message, ts }
lineno: number
formatint64
message: string
ts: string
formatdate-time
pending: optional boolean
outbound: object { lines, pending }
lines: optional array of object { lineno, message, ts }
lineno: number
formatint64
message: string
ts: string
formatdate-time
pending: optional boolean

InvestigateMove

Move a message
POST/accounts/{account_id}/email-security/investigate/{postfix_id}/move
Move multiple messages
POST/accounts/{account_id}/email-security/investigate/move
ModelsExpand Collapse
MoveCreateResponse = array of object { completed_timestamp, item_count, success, 6 more }
Deprecatedcompleted_timestamp: string

Deprecated, use completed_at instead

formatdate-time
Deprecateditem_count: number
formatint32
success: boolean
completed_at: optional string
formatdate-time
destination: optional string
message_id: optional string
operation: optional string
recipient: optional string
status: optional string
MoveBulkResponse object { completed_timestamp, item_count, success, 6 more }
Deprecatedcompleted_timestamp: string

Deprecated, use completed_at instead

formatdate-time
Deprecateditem_count: number
formatint32
success: boolean
completed_at: optional string
formatdate-time
destination: optional string
message_id: optional string
operation: optional string
recipient: optional string
status: optional string

InvestigateReclassify

Change email classification
POST/accounts/{account_id}/email-security/investigate/{postfix_id}/reclassify
ModelsExpand Collapse
ReclassifyCreateResponse = unknown

InvestigateRelease

Release messages from quarantine
POST/accounts/{account_id}/email-security/investigate/release
ModelsExpand Collapse
ReleaseBulkResponse object { id, postfix_id, delivered, 2 more }
id: string
postfix_id: string

The identifier of the message.

delivered: optional array of string
failed: optional array of string
undelivered: optional array of string