--- title: Search email messages --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api/python) [Email Security](https://developers.cloudflare.com/api/python/resources/email_security) [Investigate](https://developers.cloudflare.com/api/python/resources/email_security/subresources/investigate) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Search email messages email\_security.investigate.list(InvestigateListParams\*\*kwargs) -> SyncV4PagePaginationArray\[[InvestigateListResponse]()] GET/accounts/{account\_id}/email-security/investigate Returns information for each email that matches the provided search parameters. ##### Security
API Token The preferred authorization scheme for interacting with the Cloudflare API. Create a token. **Example:**Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key. **Example:**X-Auth-Email: user@example.com The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys. **Example:**X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
##### Accepted Permissions (at least one required) `Cloud Email Security: Write``Cloud Email Security: Read` ##### ParametersExpand Collapse account\_id: str Identifier. maxLength32 [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20account_id%20%3E%20(schema)>) alert\_id: Optional\[str] Filter by alert ID. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20alert_id%20%3E%20(schema)>) cursor: Optional\[str] Pagination cursor from the previous response’s `result_info`. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20cursor%20%3E%20(schema)>)
delivery\_status: Optional\[Literal\["delivered", "moved", "quarantined", 5 more]] Delivery status to filter by. One of the following: "delivered" Link to this property "moved" Link to this property "quarantined" Link to this property "rejected" Link to this property "deferred" Link to this property "bounced" Link to this property "queued" Link to this property "move\_failed" Link to this property
[Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20delivery_status%20%3E%20(schema)>) detections\_only: Optional\[[bool]()] Whether to include only detections in search results. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20detections_only%20%3E%20(schema)>) domain: Optional\[str] Filter by a domain found in the email — sender domain, recipient domain, or a domain in a link. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20domain%20%3E%20(schema)>) end: Optional\[Union\[str, datetime]] The end of the search date range. Defaults to `now`. formatdate-time [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20end%20%3E%20(schema)>)
final\_disposition: Optional\[Literal\["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]] Dispositions to filter by. One of the following: "MALICIOUS" Link to this property "SUSPICIOUS" Link to this property "SPOOF" Link to this property "SPAM" Link to this property "BULK" Link to this property "NONE" Link to this property
[Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20final_disposition%20%3E%20(schema)>)
message\_action: Optional\[Literal\["PREVIEW", "QUARANTINE\_RELEASED", "MOVED"]] Message actions to filter by. One of the following: "PREVIEW" Link to this property "QUARANTINE\_RELEASED" Link to this property "MOVED" Link to this property
[Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20message_action%20%3E%20(schema)>) message\_id: Optional\[str] Filter by the RFC 5322 Message-ID header. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20message_id%20%3E%20(schema)>) metric: Optional\[str] Metric to aggregate the results by. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20metric%20%3E%20(schema)>) page: Optional\[int] Deprecated: Use cursor pagination instead. End of life: November 1, 2026. minimum1 [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20page%20%3E%20(schema)>) per\_page: Optional\[int] The number of results per page. Maximum value is 1000. maximum1000 minimum1 [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20per_page%20%3E%20(schema)>) query: Optional\[str] Space-delimited term matched case-insensitively against message metadata — sender, recipient, subject, attachment names and hashes, and message ID. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20query%20%3E%20(schema)>) recipient: Optional\[str] Filter by recipient. Matches an email address or a domain. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20recipient%20%3E%20(schema)>) sender: Optional\[str] Filter by sender. Matches an email address or a domain. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20sender%20%3E%20(schema)>) smtp\_helo\_ip: Optional\[str] Matches messages whose SMTP HELO server IP address equals this value. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20smtp_helo_ip%20%3E%20(schema)>) start: Optional\[Union\[str, datetime]] The beginning of the search date range. Defaults to `now - 30 days`. Must not be in the future. formatdate-time [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20start%20%3E%20(schema)>) subject: Optional\[str] Search for messages containing individual keywords in any order within the subject. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20subject%20%3E%20(schema)>) ##### ReturnsExpand Collapse
class InvestigateListResponse: … id: str Unique identifier for a message retrieved from investigation. Link to this property
Deprecatedaction\_log: List\[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: datetime Timestamp when action completed. formatdate-time Link to this property
operation: Literal\["MOVE", "RELEASE", "RECLASSIFY", 3 more] Type of action performed. One of the following: "MOVE" Link to this property "RELEASE" Link to this property "RECLASSIFY" Link to this property "SUBMISSION" Link to this property "QUARANTINE\_RELEASE" Link to this property "PREVIEW" Link to this property
Link to this property Deprecatedcompleted\_timestamp: Optional\[str] Use completed_at instead. Deprecated, use completed_at instead. End of life: November 1, 2026. Link to this property
properties: Optional\[ActionLogProperties] Additional properties for the action. folder: Optional\[str] Target folder for move operations. Link to this property requested\_by: Optional\[str] User who requested the action. Link to this property
Link to this property status: Optional\[str] Status of the action. Link to this property
Link to this property client\_recipients: List\[str] Link to this property detection\_reasons: List\[str] Link to this property is\_phish\_submission: bool Link to this property is\_quarantined: bool Link to this property postfix\_id: str The identifier of the message. Link to this property
properties: Properties Message processing properties. allowlisted\_pattern: Optional\[str] Pattern that allowlisted this message. Link to this property
allowlisted\_pattern\_type: Optional\[Literal\["quarantine\_release", "acceptable\_sender", "allowed\_sender", 5 more]] Type of allowlist pattern. One of the following: "quarantine\_release" Link to this property "acceptable\_sender" Link to this property "allowed\_sender" Link to this property "allowed\_recipient" Link to this property "domain\_similarity" Link to this property "domain\_recency" Link to this property "managed\_acceptable\_sender" Link to this property "outbound\_ndr" Link to this property
Link to this property blocklisted\_message: Optional\[bool] Whether message was blocklisted. Link to this property blocklisted\_pattern: Optional\[str] Pattern that blocklisted this message. Link to this property
whitelisted\_pattern\_type: Optional\[Literal\["quarantine\_release", "acceptable\_sender", "allowed\_sender", 5 more]] Legacy field for allowlist pattern type. One of the following: "quarantine\_release" Link to this property "acceptable\_sender" Link to this property "allowed\_sender" Link to this property "allowed\_recipient" Link to this property "domain\_similarity" Link to this property "domain\_recency" Link to this property "managed\_acceptable\_sender" Link to this property "outbound\_ndr" Link to this property
Link to this property
Link to this property Deprecatedts: str Use scanned_at instead. Deprecated, use scanned_at instead. End of life: November 1, 2026. Link to this property alert\_id: Optional\[str] Link to this property
delivery\_mode: Optional\[Literal\["DIRECT", "BCC", "JOURNAL", 8 more]] One of the following: "DIRECT" Link to this property "BCC" Link to this property "JOURNAL" Link to this property "REVIEW\_SUBMISSION" Link to this property "DMARC\_UNVERIFIED" Link to this property "DMARC\_FAILURE\_REPORT" Link to this property "DMARC\_AGGREGATE\_REPORT" Link to this property "THREAT\_INTEL\_SUBMISSION" Link to this property "SIMULATION\_SUBMISSION" Link to this property "API" Link to this property "RETRO\_SCAN" Link to this property
Link to this property
delivery\_status: Optional\[List\[Literal\["delivered", "moved", "quarantined", 5 more]]] One of the following: "delivered" Link to this property "moved" Link to this property "quarantined" Link to this property "rejected" Link to this property "deferred" Link to this property "bounced" Link to this property "queued" Link to this property "move\_failed" Link to this property
Link to this property edf\_hash: Optional\[str] Link to this property envelope\_from: Optional\[str] Link to this property envelope\_to: Optional\[List\[str]] Link to this property
final\_disposition: Optional\[Literal\["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]] The verdict Email Security assigns to a message. One of the following: "MALICIOUS" Link to this property "MALICIOUS-BEC" Link to this property "SUSPICIOUS" Link to this property "SPOOF" Link to this property "SPAM" Link to this property "BULK" Link to this property "ENCRYPTED" Link to this property "EXTERNAL" Link to this property "UNKNOWN" Link to this property "NONE" Link to this property
Link to this property
Deprecatedfindings: Optional\[List\[Finding]] 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: Optional\[str] Link to this property detail: Optional\[str] Link to this property
detection: Optional\[Literal\["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]] The verdict Email Security assigns to a message. One of the following: "MALICIOUS" Link to this property "MALICIOUS-BEC" Link to this property "SUSPICIOUS" Link to this property "SPOOF" Link to this property "SPAM" Link to this property "BULK" Link to this property "ENCRYPTED" Link to this property "EXTERNAL" Link to this property "UNKNOWN" Link to this property "NONE" Link to this property
Link to this property field: Optional\[str] Link to this property name: Optional\[str] Link to this property portion: Optional\[str] Link to this property reason: Optional\[str] Link to this property score: Optional\[float] formatdouble Link to this property value: Optional\[str] Link to this property
Link to this property from\_: Optional\[str] Link to this property from\_name: Optional\[str] Link to this property htmltext\_structure\_hash: Optional\[str] Link to this property message\_id: Optional\[str] Link to this property
post\_delivery\_operations: Optional\[List\[Literal\["PREVIEW", "QUARANTINE\_RELEASE", "SUBMISSION", "MOVE"]]] Post-delivery operations performed on this message. One of the following: "PREVIEW" Link to this property "QUARANTINE\_RELEASE" Link to this property "SUBMISSION" Link to this property "MOVE" Link to this property
Link to this property postfix\_id\_outbound: Optional\[str] Link to this property replyto: Optional\[str] Link to this property scanned\_at: Optional\[datetime] When the message was scanned (UTC). formatdate-time Link to this property sent\_at: Optional\[datetime] When the message was sent (UTC). formatdate-time Link to this property sent\_date: Optional\[str] Link to this property smtp\_helo\_server\_ip: Optional\[str] Link to this property smtp\_previous\_hop\_ip: Optional\[str] Link to this property subject: Optional\[str] Link to this property threat\_categories: Optional\[List\[str]] Link to this property to: Optional\[List\[str]] Link to this property to\_name: Optional\[List\[str]] Link to this property
validation: Optional\[Validation] comment: Optional\[str] Link to this property
dkim: Optional\[Literal\["pass", "neutral", "fail", 2 more]] One of the following: "pass" Link to this property "neutral" Link to this property "fail" Link to this property "error" Link to this property "none" Link to this property
Link to this property
dmarc: Optional\[Literal\["pass", "neutral", "fail", 2 more]] One of the following: "pass" Link to this property "neutral" Link to this property "fail" Link to this property "error" Link to this property "none" Link to this property
Link to this property
spf: Optional\[Literal\["pass", "neutral", "fail", 2 more]] One of the following: "pass" Link to this property "neutral" Link to this property "fail" Link to this property "error" Link to this property "none" Link to this property
Link to this property
Link to this property x\_originating\_ip: Optional\[str] Link to this property
[Link to this property](<#(resource)%20email_security.investigate%20%3E%20(model)%20investigate_list_response%20%3E%20(schema)>) ### Search email messages Python HTTPTypeScriptPythonGoTerraform ``` import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.investigate.list( account_id="023e105f4ecef8ad9ca31a8372d0c353", ) page = page.result[0] print(page.id) ``` 200 example ``` { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "id": "4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678", "action_log": [ { "completed_at": "2019-12-27T18:11:19.117Z", "operation": "MOVE", "completed_timestamp": "completed_timestamp", "properties": { "folder": "folder", "requested_by": "requested_by" }, "status": "status" } ], "client_recipients": [ "string" ], "detection_reasons": [ "string" ], "is_phish_submission": true, "is_quarantined": true, "postfix_id": "4Njp3P0STMz2c02Q", "properties": { "allowlisted_pattern": "allowlisted_pattern", "allowlisted_pattern_type": "quarantine_release", "blocklisted_message": true, "blocklisted_pattern": "blocklisted_pattern", "whitelisted_pattern_type": "quarantine_release" }, "ts": "ts", "alert_id": "alert_id", "delivery_mode": "DIRECT", "delivery_status": [ "delivered" ], "edf_hash": "edf_hash", "envelope_from": "envelope_from", "envelope_to": [ "string" ], "final_disposition": "MALICIOUS", "findings": [ { "attachment": "attachment", "detail": "detail", "detection": "MALICIOUS", "field": "field", "name": "name", "portion": "portion", "reason": "reason", "score": 0, "value": "value" } ], "from": "from", "from_name": "from_name", "htmltext_structure_hash": "htmltext_structure_hash", "message_id": "message_id", "post_delivery_operations": [ "PREVIEW" ], "postfix_id_outbound": "postfix_id_outbound", "replyto": "replyto", "scanned_at": "2019-12-27T18:11:19.117Z", "sent_at": "2019-12-27T18:11:19.117Z", "sent_date": "sent_date", "smtp_helo_server_ip": "smtp_helo_server_ip", "smtp_previous_hop_ip": "smtp_previous_hop_ip", "subject": "subject", "threat_categories": [ "string" ], "to": [ "string" ], "to_name": [ "string" ], "validation": { "comment": "comment", "dkim": "pass", "dmarc": "pass", "spf": "pass" }, "x_originating_ip": "x_originating_ip" } ], "result_info": { "count": 0, "per_page": 0, "total_count": 0, "next": "next", "page": 0, "previous": "previous" }, "success": true } ``` ##### Returns Examples 200 example ``` { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "id": "4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678", "action_log": [ { "completed_at": "2019-12-27T18:11:19.117Z", "operation": "MOVE", "completed_timestamp": "completed_timestamp", "properties": { "folder": "folder", "requested_by": "requested_by" }, "status": "status" } ], "client_recipients": [ "string" ], "detection_reasons": [ "string" ], "is_phish_submission": true, "is_quarantined": true, "postfix_id": "4Njp3P0STMz2c02Q", "properties": { "allowlisted_pattern": "allowlisted_pattern", "allowlisted_pattern_type": "quarantine_release", "blocklisted_message": true, "blocklisted_pattern": "blocklisted_pattern", "whitelisted_pattern_type": "quarantine_release" }, "ts": "ts", "alert_id": "alert_id", "delivery_mode": "DIRECT", "delivery_status": [ "delivered" ], "edf_hash": "edf_hash", "envelope_from": "envelope_from", "envelope_to": [ "string" ], "final_disposition": "MALICIOUS", "findings": [ { "attachment": "attachment", "detail": "detail", "detection": "MALICIOUS", "field": "field", "name": "name", "portion": "portion", "reason": "reason", "score": 0, "value": "value" } ], "from": "from", "from_name": "from_name", "htmltext_structure_hash": "htmltext_structure_hash", "message_id": "message_id", "post_delivery_operations": [ "PREVIEW" ], "postfix_id_outbound": "postfix_id_outbound", "replyto": "replyto", "scanned_at": "2019-12-27T18:11:19.117Z", "sent_at": "2019-12-27T18:11:19.117Z", "sent_date": "sent_date", "smtp_helo_server_ip": "smtp_helo_server_ip", "smtp_previous_hop_ip": "smtp_previous_hop_ip", "subject": "subject", "threat_categories": [ "string" ], "to": [ "string" ], "to_name": [ "string" ], "validation": { "comment": "comment", "dkim": "pass", "dmarc": "pass", "spf": "pass" }, "x_originating_ip": "x_originating_ip" } ], "result_info": { "count": 0, "per_page": 0, "total_count": 0, "next": "next", "page": 0, "previous": "previous" }, "success": true } ```