Search email messages
GET/accounts/{account_id}/email-security/investigate
Returns information for each email that matches the search parameter(s). If the search takes too long, the endpoint returns 202 with a Location header pointing to a polling endpoint where results can be retrieved once ready.
Security
API Email + API Key
The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.
Example:
The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.
Example:
Accepted Permissions (at least one required)
Query Parameters
domain: optional string
Filter by a domain found in the email: sender domain, recipient domain, or a domain in a link.
end: optional string
The end of the search date range.
Defaults to now if not provided.
formatdate-time
query: optional string
The space-delimited term used in the query. The search is case-insensitive.
The content of the following email metadata fields are searched:
- alert_id
- CC
- From (envelope_from)
- From Name
- final_disposition
- md5 hash (of any attachment)
- sha1 hash (of any attachment)
- sha256 hash (of any attachment)
- name (of any attachment)
- Reason
- Received DateTime (yyyy-mm-ddThh:mm:ss)
- Sent DateTime (yyyy-mm-ddThh:mm:ss)
- ReplyTo
- To (envelope_to)
- To Name
- Message-ID
- smtp_helo_server_ip
- smtp_previous_hop_ip
- x_originating_ip
- Subject
start: optional string
The beginning of the search date range.
Defaults to now - 30 days if not provided.
formatdate-time
Search email messages
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"{
"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-2022-12-30T02:44:49-2a539d65",
"action_log": [],
"client_recipients": [
"email@example.com"
],
"detection_reasons": [
"Selector is a source of spam/uce : Smtp-Helo-Server-Ip=<b>127.0.0[dot]186</b>"
],
"is_phish_submission": false,
"is_quarantined": false,
"postfix_id": "47JJcT1w6GztQV7",
"properties": {
"allowlisted_pattern": "allowlisted_pattern",
"allowlisted_pattern_type": "quarantine_release",
"blocklisted_message": true,
"blocklisted_pattern": "blocklisted_pattern",
"whitelisted_pattern_type": "quarantine_release"
},
"ts": "2019-11-20T23:22:01",
"alert_id": "4Njp3P0STMz2c02Q-2022-12-30T02:44:49",
"delivery_mode": "DIRECT",
"edf_hash": null,
"envelope_from": "d1994@example.com",
"envelope_to": [
"email@example.com"
],
"final_disposition": "MALICIOUS",
"findings": [
{
"attachment": "attachment",
"detail": "detail",
"detection": "MALICIOUS",
"field": "field",
"name": "name",
"portion": "portion",
"reason": "reason",
"score": 0,
"value": "value"
}
],
"from": "d1994@example.com",
"from_name": "Sender Name",
"htmltext_structure_hash": null,
"message_id": "<4VAZPrAdg7IGNxdt1DWRNu0gvOeL_iZiwP4BQfo4DaE.Yw-woXuugQbeFhBpzwFQtqq_v2v1HOKznoMBqbciQpE@example.com>",
"post_delivery_operations": [
"PREVIEW"
],
"postfix_id_outbound": null,
"replyto": "email@example.com",
"scanned_at": "2019-11-20T23:22:01Z",
"sent_at": "2019-11-21T00:22:01Z",
"sent_date": "2019-11-21T00:22:01",
"subject": "listen, I highly recommend u to read that email, just to ensure not a thing will take place",
"threat_categories": [
"IPReputation",
"ASNReputation"
],
"to": [
"email@example.com"
],
"to_name": [
"Recipient Name"
],
"validation": {
"comment": null,
"dkim": "pass",
"dmarc": "none",
"spf": "fail"
}
}
],
"result_info": {
"count": 0,
"page": 0,
"per_page": 0,
"total_count": 0,
"next": "next",
"previous": "previous"
},
"success": true
}Returns Examples
{
"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-2022-12-30T02:44:49-2a539d65",
"action_log": [],
"client_recipients": [
"email@example.com"
],
"detection_reasons": [
"Selector is a source of spam/uce : Smtp-Helo-Server-Ip=<b>127.0.0[dot]186</b>"
],
"is_phish_submission": false,
"is_quarantined": false,
"postfix_id": "47JJcT1w6GztQV7",
"properties": {
"allowlisted_pattern": "allowlisted_pattern",
"allowlisted_pattern_type": "quarantine_release",
"blocklisted_message": true,
"blocklisted_pattern": "blocklisted_pattern",
"whitelisted_pattern_type": "quarantine_release"
},
"ts": "2019-11-20T23:22:01",
"alert_id": "4Njp3P0STMz2c02Q-2022-12-30T02:44:49",
"delivery_mode": "DIRECT",
"edf_hash": null,
"envelope_from": "d1994@example.com",
"envelope_to": [
"email@example.com"
],
"final_disposition": "MALICIOUS",
"findings": [
{
"attachment": "attachment",
"detail": "detail",
"detection": "MALICIOUS",
"field": "field",
"name": "name",
"portion": "portion",
"reason": "reason",
"score": 0,
"value": "value"
}
],
"from": "d1994@example.com",
"from_name": "Sender Name",
"htmltext_structure_hash": null,
"message_id": "<4VAZPrAdg7IGNxdt1DWRNu0gvOeL_iZiwP4BQfo4DaE.Yw-woXuugQbeFhBpzwFQtqq_v2v1HOKznoMBqbciQpE@example.com>",
"post_delivery_operations": [
"PREVIEW"
],
"postfix_id_outbound": null,
"replyto": "email@example.com",
"scanned_at": "2019-11-20T23:22:01Z",
"sent_at": "2019-11-21T00:22:01Z",
"sent_date": "2019-11-21T00:22:01",
"subject": "listen, I highly recommend u to read that email, just to ensure not a thing will take place",
"threat_categories": [
"IPReputation",
"ASNReputation"
],
"to": [
"email@example.com"
],
"to_name": [
"Recipient Name"
],
"validation": {
"comment": null,
"dkim": "pass",
"dmarc": "none",
"spf": "fail"
}
}
],
"result_info": {
"count": 0,
"page": 0,
"per_page": 0,
"total_count": 0,
"next": "next",
"previous": "previous"
},
"success": true
}