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, 17 more } params, RequestOptionsoptions?): V4PagePaginationArray<InvestigateListResponse { id, action_log, client_recipients, 28 more } >
GET/accounts/{account_id}/email-security/investigate
Get message details
client.emailSecurity.investigate.get(stringpostfixId, InvestigateGetParams { account_id } params, RequestOptionsoptions?): InvestigateGetResponse { id, action_log, client_recipients, 28 more }
GET/accounts/{account_id}/email-security/investigate/{postfix_id}
ModelsExpand Collapse
InvestigateListResponse { id, action_log, client_recipients, 28 more }
id: string
action_log: unknown
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 }
allowlisted_pattern?: string
allowlisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 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?: boolean
blocklisted_pattern?: string
whitelisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 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?: 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"
edf_hash?: string | null
envelope_from?: string | null
envelope_to?: Array<string> | null
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
findings?: Array<Finding> | null
attachment?: string | null
detail?: string | null
detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null
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">
One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound?: string | null
replyto?: string | null
scanned_at?: string
formatdate-time
sent_at?: string
formatdate-time
Deprecatedsent_date?: string | null

Deprecated, use sent_at instead

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"
InvestigateGetResponse { id, action_log, client_recipients, 28 more }
id: string
action_log: unknown
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 }
allowlisted_pattern?: string
allowlisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 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?: boolean
blocklisted_pattern?: string
whitelisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 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?: 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"
edf_hash?: string | null
envelope_from?: string | null
envelope_to?: Array<string> | null
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
findings?: Array<Finding> | null
attachment?: string | null
detail?: string | null
detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null
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">
One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound?: string | null
replyto?: string | null
scanned_at?: string
formatdate-time
sent_at?: string
formatdate-time
Deprecatedsent_date?: string | null

Deprecated, use sent_at instead

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"

InvestigateDetections

Get message detection details
client.emailSecurity.investigate.detections.get(stringpostfixId, DetectionGetParams { account_id } params, RequestOptionsoptions?): DetectionGetResponse { action, attachments, headers, 5 more }
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/detections
ModelsExpand Collapse
DetectionGetResponse { action, attachments, headers, 5 more }
action: string
attachments: Array<Attachment>
size: number
minimum0
content_type?: string | null
detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
encrypted?: boolean | null
name?: 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.

formatint64
geo?: string | null
ip?: string | null
pld?: string | null
threat_categories: Array<ThreatCategory>
id: number
formatint64
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
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"

InvestigatePreview

Get email preview
client.emailSecurity.investigate.preview.get(stringpostfixId, PreviewGetParams { account_id } params, RequestOptionsoptions?): PreviewGetResponse { screenshot }
GET/accounts/{account_id}/email-security/investigate/{postfix_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(stringpostfixId, RawGetParams { account_id } params, RequestOptionsoptions?): RawGetResponse { raw }
GET/accounts/{account_id}/email-security/investigate/{postfix_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(stringpostfixId, TraceGetParams { account_id } params, RequestOptionsoptions?): TraceGetResponse { inbound, outbound }
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/trace
ModelsExpand Collapse
TraceGetResponse { inbound, outbound }
inbound: Inbound { lines, pending }
lines?: Array<Line> | null
lineno: number
formatint64
message: string
ts: string
formatdate-time
pending?: boolean | null
outbound: Outbound { lines, pending }
lines?: Array<Line> | null
lineno: number
formatint64
message: string
ts: string
formatdate-time
pending?: boolean | null

InvestigateMove

Move a message
client.emailSecurity.investigate.move.create(stringpostfixId, MoveCreateParams { account_id, destination } params, RequestOptionsoptions?): SinglePage<MoveCreateResponse { completed_timestamp, item_count, success, 6 more } >
POST/accounts/{account_id}/email-security/investigate/{postfix_id}/move
Move multiple messages
client.emailSecurity.investigate.move.bulk(MoveBulkParams { account_id, destination, ids, postfix_ids } params, RequestOptionsoptions?): SinglePage<MoveBulkResponse { completed_timestamp, item_count, success, 6 more } >
POST/accounts/{account_id}/email-security/investigate/move
ModelsExpand Collapse
MoveCreateResponse { 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?: string
formatdate-time
destination?: string | null
message_id?: string | null
operation?: string | null
recipient?: string | null
status?: string | null
MoveBulkResponse { 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?: string
formatdate-time
destination?: string | null
message_id?: string | null
operation?: string | null
recipient?: string | null
status?: string | null

InvestigateReclassify

Change email classification
client.emailSecurity.investigate.reclassify.create(stringpostfixId, ReclassifyCreateParams { account_id, expected_disposition, eml_content, escalated_submission_id } params, RequestOptionsoptions?): ReclassifyCreateResponse
POST/accounts/{account_id}/email-security/investigate/{postfix_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, postfix_id, delivered, 2 more } >
POST/accounts/{account_id}/email-security/investigate/release
ModelsExpand Collapse
ReleaseBulkResponse { id, postfix_id, delivered, 2 more }
id: string
postfix_id: string

The identifier of the message.

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