--- title: Search email messages --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api) [Email Security](https://developers.cloudflare.com/api/resources/email_security) [Investigate](https://developers.cloudflare.com/api/resources/email_security/subresources/investigate) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Search email messages 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` ##### P ath ParametersExpand Collapse account\_id: string 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)>) ##### Q uery ParametersExpand Collapse alert\_id: optional string 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 string 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 "delivered"or "moved"or "quarantined"or 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 boolean 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 string 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 string 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 "MALICIOUS"or "SUSPICIOUS"or "SPOOF"or 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 "PREVIEW"or "QUARANTINE\_RELEASED"or "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 string 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 string 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 number 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 number 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 string 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 string 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 string 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 string 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 string 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 string 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

errors: array of object {code, message, documentation\_url, source }

code: number minimum1000 Link to this property message: string Link to this property documentation\_url: optional string Link to this property

source: optional object {pointer }

pointer: optional string Link to this property

Link to this property

[Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(network%20schema)%20%3E%20(property)%20errors>)

messages: array of object {code, message, documentation\_url, source }

code: number minimum1000 Link to this property message: string Link to this property documentation\_url: optional string Link to this property

source: optional object {pointer }

pointer: optional string Link to this property

Link to this property

[Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(network%20schema)%20%3E%20(property)%20messages>)

result: array of object {id, action\_log, client\_recipients, 32 more }

id: string Unique identifier for a message retrieved from investigation. Link to this property

Deprecatedaction\_log: array of object {completed\_at, operation, completed\_timestamp, 2 more } 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: string Timestamp when action completed. formatdate-time Link to this property

operation: "MOVE"or "RELEASE"or "RECLASSIFY"or 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 string Use completed_at instead. Deprecated, use completed_at instead. End of life: November 1, 2026. Link to this property

properties: optional object {folder, requested\_by } Additional properties for the action.

folder: optional string Target folder for move operations. Link to this property requested\_by: optional string User who requested the action. Link to this property

Link to this property status: optional string Status of the action. Link to this property

Link to this property client\_recipients: array of string Link to this property detection\_reasons: array of string Link to this property is\_phish\_submission: boolean Link to this property is\_quarantined: boolean Link to this property postfix\_id: string The identifier of the message. Link to this property

properties: object {allowlisted\_pattern, allowlisted\_pattern\_type, blocklisted\_message, 2 more } Message processing properties.

allowlisted\_pattern: optional string Pattern that allowlisted this message. Link to this property

allowlisted\_pattern\_type: optional "quarantine\_release"or "acceptable\_sender"or "allowed\_sender"or 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 boolean Whether message was blocklisted. Link to this property blocklisted\_pattern: optional string Pattern that blocklisted this message. Link to this property

whitelisted\_pattern\_type: optional "quarantine\_release"or "acceptable\_sender"or "allowed\_sender"or 5 more Legacy field for allowlist pattern type.

Link to this property

Link to this property Deprecatedts: string Use scanned_at instead. Deprecated, use scanned_at instead. End of life: November 1, 2026. Link to this property alert\_id: optional string Link to this property

delivery\_mode: optional "DIRECT"or "BCC"or "JOURNAL"or 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 array of "delivered"or "moved"or "quarantined"or 5 more

Link to this property edf\_hash: optional string Link to this property envelope\_from: optional string Link to this property envelope\_to: optional array of string Link to this property

final\_disposition: optional "MALICIOUS"or "MALICIOUS-BEC"or "SUSPICIOUS"or 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 array of object {attachment, detail, detection, 6 more } 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 string Link to this property detail: optional string Link to this property

detection: optional "MALICIOUS"or "MALICIOUS-BEC"or "SUSPICIOUS"or 7 more The verdict Email Security assigns to a message.

Link to this property field: optional string Link to this property name: optional string Link to this property portion: optional string Link to this property reason: optional string Link to this property score: optional number formatdouble Link to this property value: optional string Link to this property

Link to this property from: optional string Link to this property from\_name: optional string Link to this property htmltext\_structure\_hash: optional string Link to this property message\_id: optional string Link to this property

post\_delivery\_operations: optional array of "PREVIEW"or "QUARANTINE\_RELEASE"or "SUBMISSION"or "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 string Link to this property replyto: optional string Link to this property scanned\_at: optional string When the message was scanned (UTC). formatdate-time Link to this property sent\_at: optional string When the message was sent (UTC). formatdate-time Link to this property sent\_date: optional string Link to this property smtp\_helo\_server\_ip: optional string Link to this property smtp\_previous\_hop\_ip: optional string Link to this property subject: optional string Link to this property threat\_categories: optional array of string Link to this property to: optional array of string Link to this property to\_name: optional array of string Link to this property

validation: optional object {comment, dkim, dmarc, spf }

comment: optional string Link to this property

dkim: optional "pass"or "neutral"or "fail"or 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 "pass"or "neutral"or "fail"or 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 "pass"or "neutral"or "fail"or 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 string Link to this property

[Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(network%20schema)%20%3E%20(property)%20result>)

result\_info: object {count, per\_page, total\_count, 3 more }

count: number Number of items in current page. minimum0 Link to this property per\_page: number Number of items per page. minimum0 Link to this property Deprecatedtotal\_count: number This field always returns 0 and is deprecated. Deprecated: Always returns 0. End of life: November 1, 2026. minimum0 Link to this property next: optional string Cursor for next page. Link to this property Deprecatedpage: optional number This field always returns 0 and is deprecated. Deprecated: Always returns 0. End of life: November 1, 2026. minimum0 Link to this property previous: optional string Cursor for previous page. Link to this property

[Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(network%20schema)%20%3E%20(property)%20result_info>) success: true Whether the API call was successful. [Link to this property](<#(resource)%20email_security.investigate%20%3E%20(method)%20list%20%3E%20(network%20schema)%20%3E%20(property)%20success>) ### Search email messages HTTP HTTPTypeScriptPythonGoTerraform ``` curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` 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 } ```