investigate

Creates, updates, deletes, gets or lists an investigate resource.

Overview

Name	investigate
Type	Resource
Id	cloudflare.email_security.investigate

Fields

The following fields are returned by SELECT queries:

get

Email message details.

Name	Datatype	Description
id	string	Unique identifier for a message retrieved from investigation (example: 4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678)
alert_id	string
message_id	string
postfix_id	string	The identifier of the message (example: 4Njp3P0STMz2c02Q)
from_name	string
to_name	array
action_log	array	Deprecated, use GET /investigate/{investigate_id}/action_log instead. End of life: November 1, 2026.
client_recipients	array
delivery_mode	string	(DIRECT, BCC, JOURNAL, REVIEW_SUBMISSION, DMARC_UNVERIFIED, DMARC_FAILURE_REPORT, DMARC_AGGREGATE_REPORT, THREAT_INTEL_SUBMISSION, SIMULATION_SUBMISSION, API, RETRO_SCAN)
delivery_status	array
detection_reasons	array
edf_hash	string
envelope_from	string
envelope_to	array
final_disposition	string	(MALICIOUS, MALICIOUS-BEC, SUSPICIOUS, SPOOF, SPAM, BULK, ENCRYPTED, EXTERNAL, UNKNOWN, NONE)
findings	array	Deprecated, use the findings field from GET /investigate/{investigate_id}/detections instead. End of life: November 1, 2026. Detection findings for this message.
from	string
htmltext_structure_hash	string
is_phish_submission	boolean
is_quarantined	boolean
post_delivery_operations	array	Post-delivery operations performed on this message
postfix_id_outbound	string
properties	object	Message processing properties
replyto	string
scanned_at	string (date-time)	When the message was scanned (UTC)
sent_at	string (date-time)	When the message was sent (UTC)
sent_date	string
subject	string
threat_categories	array
to	array
ts	string	Deprecated, use scanned_at instead. End of life: November 1, 2026.
validation	object

list

Search results for the provided query.

Name	Datatype	Description
id	string	Unique identifier for a message retrieved from investigation (example: 4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678)
alert_id	string
message_id	string
postfix_id	string	The identifier of the message (example: 4Njp3P0STMz2c02Q)
from_name	string
to_name	array
action_log	array	Deprecated, use GET /investigate/{investigate_id}/action_log instead. End of life: November 1, 2026.
client_recipients	array
delivery_mode	string	(DIRECT, BCC, JOURNAL, REVIEW_SUBMISSION, DMARC_UNVERIFIED, DMARC_FAILURE_REPORT, DMARC_AGGREGATE_REPORT, THREAT_INTEL_SUBMISSION, SIMULATION_SUBMISSION, API, RETRO_SCAN)
delivery_status	array
detection_reasons	array
edf_hash	string
envelope_from	string
envelope_to	array
final_disposition	string	(MALICIOUS, MALICIOUS-BEC, SUSPICIOUS, SPOOF, SPAM, BULK, ENCRYPTED, EXTERNAL, UNKNOWN, NONE)
findings	array	Deprecated, use the findings field from GET /investigate/{investigate_id}/detections instead. End of life: November 1, 2026. Detection findings for this message.
from	string
htmltext_structure_hash	string
is_phish_submission	boolean
is_quarantined	boolean
post_delivery_operations	array	Post-delivery operations performed on this message
postfix_id_outbound	string
properties	object	Message processing properties
replyto	string
scanned_at	string (date-time)	When the message was scanned (UTC)
sent_at	string (date-time)	When the message was sent (UTC)
sent_date	string
subject	string
threat_categories	array
to	array
ts	string	Deprecated, use scanned_at instead. End of life: November 1, 2026.
validation	object

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	account_id, investigate_id	submission	Retrieves comprehensive details for a specific email message including headers, recipients, sender information, and current quarantine status. Use the investigate_id from search results to fetch detailed information.
list	select	account_id	start, end, query, detections_only, action_log, final_disposition, metric, message_action, recipient, sender, alert_id, domain, message_id, subject, cursor, per_page, page	Returns information for each email that matches the search parameter(s).
bulk_move	exec	account_id, destination		Moves multiple messages to a specified mailbox folder (Inbox, JunkEmail, DeletedItems, RecoverableItemsDeletions, or RecoverableItemsPurges). Requires active integration.
release	exec	account_id		Releases one or more quarantined messages, delivering them to the intended recipients. Use when a message was incorrectly quarantined. Returns delivery status for each recipient.
move_message	exec	account_id, investigate_id, destination		Moves a single message to a specified mailbox folder (Inbox, JunkEmail, DeletedItems, RecoverableItemsDeletions, or RecoverableItemsPurges). Requires active integration.
reclassify	exec	account_id, investigate_id, expected_disposition		Submits a request to reclassify an email's disposition. Use for reporting false positives or false negatives. Optionally provide the raw EML content for reanalysis. The reclassification is processed asynchronously.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
account_id	string	The Cloudflare account ID.
investigate_id	string
action_log	boolean	Whether to include the message action log in the response.
alert_id	string
cursor	string
detections_only	boolean	Whether to include only detections in search results.
domain	string	Sender domains to filter by.
end	string (date-time)	The end of the search date range. Defaults to now.
final_disposition	string	Dispositions to filter by.
message_action	string	Message actions to filter by.
message_id	string
metric	string
page	integer	Deprecated: Use cursor pagination instead. End of life: November 1, 2026.
per_page	integer	The number of results per page. Maximum value is 1000.
query	string	Space-delimited search term. Case-insensitive.
recipient	string
sender	string
start	string (date-time)	The beginning of the search date range. Defaults to now - 30 days.
subject	string
submission	boolean	When true, search the submissions datastore only. When false or omitted, search the regular datastore only.

SELECT examples

get

Retrieves comprehensive details for a specific email message including headers, recipients, sender information, and current quarantine status. Use the investigate_id from search results to fetch detailed information.

SELECT
id,
alert_id,
message_id,
postfix_id,
from_name,
to_name,
action_log,
client_recipients,
delivery_mode,
delivery_status,
detection_reasons,
edf_hash,
envelope_from,
envelope_to,
final_disposition,
findings,
from,
htmltext_structure_hash,
is_phish_submission,
is_quarantined,
post_delivery_operations,
postfix_id_outbound,
properties,
replyto,
scanned_at,
sent_at,
sent_date,
subject,
threat_categories,
to,
ts,
validation
FROM cloudflare.email_security.investigate
WHERE account_id = '{{ account_id }}' -- required
AND investigate_id = '{{ investigate_id }}' -- required
AND submission = '{{ submission }}'
;

list

Returns information for each email that matches the search parameter(s).

SELECT
id,
alert_id,
message_id,
postfix_id,
from_name,
to_name,
action_log,
client_recipients,
delivery_mode,
delivery_status,
detection_reasons,
edf_hash,
envelope_from,
envelope_to,
final_disposition,
findings,
from,
htmltext_structure_hash,
is_phish_submission,
is_quarantined,
post_delivery_operations,
postfix_id_outbound,
properties,
replyto,
scanned_at,
sent_at,
sent_date,
subject,
threat_categories,
to,
ts,
validation
FROM cloudflare.email_security.investigate
WHERE account_id = '{{ account_id }}' -- required
AND start = '{{ start }}'
AND end = '{{ end }}'
AND query = '{{ query }}'
AND detections_only = '{{ detections_only }}'
AND action_log = '{{ action_log }}'
AND final_disposition = '{{ final_disposition }}'
AND metric = '{{ metric }}'
AND message_action = '{{ message_action }}'
AND recipient = '{{ recipient }}'
AND sender = '{{ sender }}'
AND alert_id = '{{ alert_id }}'
AND domain = '{{ domain }}'
AND message_id = '{{ message_id }}'
AND subject = '{{ subject }}'
AND cursor = '{{ cursor }}'
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

Lifecycle Methods

bulk_move

Moves multiple messages to a specified mailbox folder (Inbox, JunkEmail, DeletedItems, RecoverableItemsDeletions, or RecoverableItemsPurges). Requires active integration.

EXEC cloudflare.email_security.investigate.bulk_move 
@account_id='{{ account_id }}' --required 
@@json=
'{
"destination": "{{ destination }}", 
"ids": "{{ ids }}", 
"postfix_ids": "{{ postfix_ids }}"
}'
;

release

Releases one or more quarantined messages, delivering them to the intended recipients. Use when a message was incorrectly quarantined. Returns delivery status for each recipient.

EXEC cloudflare.email_security.investigate.release 
@account_id='{{ account_id }}' --required
;

move_message

Moves a single message to a specified mailbox folder (Inbox, JunkEmail, DeletedItems, RecoverableItemsDeletions, or RecoverableItemsPurges). Requires active integration.

EXEC cloudflare.email_security.investigate.move_message 
@account_id='{{ account_id }}' --required, 
@investigate_id='{{ investigate_id }}' --required 
@@json=
'{
"destination": "{{ destination }}"
}'
;

reclassify

Submits a request to reclassify an email's disposition. Use for reporting false positives or false negatives. Optionally provide the raw EML content for reanalysis. The reclassification is processed asynchronously.

EXEC cloudflare.email_security.investigate.reclassify 
@account_id='{{ account_id }}' --required, 
@investigate_id='{{ investigate_id }}' --required 
@@json=
'{
"eml_content": "{{ eml_content }}", 
"escalated_submission_id": "{{ escalated_submission_id }}", 
"expected_disposition": "{{ expected_disposition }}"
}'
;