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(strpostfix_id, InvestigateGetParams**kwargs) -> InvestigateGetResponse
GET/accounts/{account_id}/email-security/investigate/{postfix_id}
ModelsExpand Collapse
class InvestigateListResponse: …
id: str
action_log: object
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
allowlisted_pattern: Optional[str]
allowlisted_pattern_type: Optional[Literal["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: Optional[bool]
blocklisted_pattern: Optional[str]
whitelisted_pattern_type: Optional[Literal["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: str

Deprecated, use scanned_at instead

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"
edf_hash: Optional[str]
envelope_from: Optional[str]
envelope_to: Optional[List[str]]
final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
findings: Optional[List[Finding]]
attachment: Optional[str]
detail: Optional[str]
detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]
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"]]]
One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound: Optional[str]
replyto: Optional[str]
scanned_at: Optional[datetime]
formatdate-time
sent_at: Optional[datetime]
formatdate-time
Deprecatedsent_date: Optional[str]

Deprecated, use sent_at instead

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"
class InvestigateGetResponse: …
id: str
action_log: object
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
allowlisted_pattern: Optional[str]
allowlisted_pattern_type: Optional[Literal["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: Optional[bool]
blocklisted_pattern: Optional[str]
whitelisted_pattern_type: Optional[Literal["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: str

Deprecated, use scanned_at instead

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"
edf_hash: Optional[str]
envelope_from: Optional[str]
envelope_to: Optional[List[str]]
final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
findings: Optional[List[Finding]]
attachment: Optional[str]
detail: Optional[str]
detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]
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"]]]
One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound: Optional[str]
replyto: Optional[str]
scanned_at: Optional[datetime]
formatdate-time
sent_at: Optional[datetime]
formatdate-time
Deprecatedsent_date: Optional[str]

Deprecated, use sent_at instead

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"

InvestigateDetections

Get message detection details
email_security.investigate.detections.get(strpostfix_id, DetectionGetParams**kwargs) -> DetectionGetResponse
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/detections
ModelsExpand Collapse
class DetectionGetResponse: …
action: str
attachments: List[Attachment]
size: int
minimum0
content_type: Optional[str]
detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
encrypted: Optional[bool]
name: 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.

formatint64
geo: Optional[str]
ip: Optional[str]
pld: Optional[str]
threat_categories: List[ThreatCategory]
id: int
formatint64
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]]
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"

InvestigatePreview

Get email preview
email_security.investigate.preview.get(strpostfix_id, PreviewGetParams**kwargs) -> PreviewGetResponse
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/preview
Preview for non-detection messages
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(strpostfix_id, RawGetParams**kwargs) -> RawGetResponse
GET/accounts/{account_id}/email-security/investigate/{postfix_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(strpostfix_id, TraceGetParams**kwargs) -> TraceGetResponse
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/trace
ModelsExpand Collapse
class TraceGetResponse: …
inbound: Inbound
lines: Optional[List[InboundLine]]
lineno: int
formatint64
message: str
ts: datetime
formatdate-time
pending: Optional[bool]
outbound: Outbound
lines: Optional[List[OutboundLine]]
lineno: int
formatint64
message: str
ts: datetime
formatdate-time
pending: Optional[bool]

InvestigateMove

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

Deprecated, use completed_at instead

formatdate-time
Deprecateditem_count: int
formatint32
success: bool
completed_at: Optional[datetime]
formatdate-time
destination: Optional[str]
message_id: Optional[str]
operation: Optional[str]
recipient: Optional[str]
status: Optional[str]
class MoveBulkResponse: …
Deprecatedcompleted_timestamp: datetime

Deprecated, use completed_at instead

formatdate-time
Deprecateditem_count: int
formatint32
success: bool
completed_at: Optional[datetime]
formatdate-time
destination: Optional[str]
message_id: Optional[str]
operation: Optional[str]
recipient: Optional[str]
status: Optional[str]

InvestigateReclassify

Change email classification
email_security.investigate.reclassify.create(strpostfix_id, ReclassifyCreateParams**kwargs) -> object
POST/accounts/{account_id}/email-security/investigate/{postfix_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
postfix_id: str

The identifier of the message.

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