Skip to content
Cloudflare API
Start here
API Reference
Email Security
Investigate

Search email messages

client.emailSecurity.investigate.list(InvestigateListParams { account_id, action_log, alert_id, 17 more } params, RequestOptionsoptions?): V4PagePaginationArray<InvestigateListResponse { id, action_log, client_recipients, 28 more } >
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: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: WriteCloud Email Security: Read
ParametersExpand Collapse
params: InvestigateListParams { account_id, action_log, alert_id, 17 more }
account_id: string

Path param: Account Identifier

maxLength32
minLength32
action_log?: boolean

Query param: Determines if the message action log is included in the response.

alert_id?: string

Query param

cursor?: string

Query param

detections_only?: boolean

Query param: Determines if the search results will include detections or not.

domain?: string

Query param: Filter by a domain found in the email: sender domain, recipient domain, or a domain in a link.

end?: string

Query param: The end of the search date range. Defaults to now if not provided.

formatdate-time
exact_subject?: string

Query param: Search for messages with an exact subject match.

final_disposition?: "MALICIOUS" | "SUSPICIOUS" | "SPOOF" | 3 more

Query param: The dispositions the search filters by.

One of the following:
"MALICIOUS"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"NONE"
message_action?: "PREVIEW" | "QUARANTINE_RELEASED" | "MOVED" | "SUBMITTED"

Query param: The message actions the search filters by.

One of the following:
"PREVIEW"
"QUARANTINE_RELEASED"
"MOVED"
"SUBMITTED"
message_id?: string

Query param

metric?: string

Query param

page?: number | null

Query param: Deprecated: Use cursor pagination instead.

formatint32
minimum1
per_page?: number

Query param: The number of results per page.

formatint32
minimum1
query?: string

Query param: 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
recipient?: string

Query param: Filter by recipient. Matches either an email address or a domain.

sender?: string

Query param: Filter by sender. Matches either an email address or a domain.

start?: string

Query param: The beginning of the search date range. Defaults to now - 30 days if not provided.

formatdate-time
subject?: string

Query param: Search for messages containing individual keywords in any order within the subject.

submissions?: boolean

Query param: Search for submissions instead of original messages

ReturnsExpand Collapse
InvestigateListResponse { id, action_log, client_recipients, 28 more }
id: string
action_log: unknown
client_recipients: Array<string>
detection_reasons: Array<string>
is_phish_submission: boolean
is_quarantined: boolean
postfix_id: string

The identifier of the message.

properties: Properties { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }
allowlisted_pattern?: string
allowlisted_pattern_type?: "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?: boolean
blocklisted_pattern?: string
whitelisted_pattern_type?: "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: string

Deprecated, use scanned_at instead

alert_id?: string | null
delivery_mode?: "DIRECT" | "BCC" | "JOURNAL" | 8 more | null
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?: string | null
envelope_from?: string | null
envelope_to?: Array<string> | null
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
findings?: Array<Finding> | null
attachment?: string | null
detail?: string | null
detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
field?: string | null
name?: string | null
portion?: string | null
reason?: string | null
score?: number | null
formatdouble
value?: string | null
from?: string | null
from_name?: string | null
htmltext_structure_hash?: string | null
message_id?: string | null
post_delivery_operations?: Array<"PREVIEW" | "QUARANTINE_RELEASE" | "SUBMISSION" | "MOVE">
One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound?: string | null
replyto?: string | null
scanned_at?: string
formatdate-time
sent_at?: string
formatdate-time
Deprecatedsent_date?: string | null

Deprecated, use sent_at instead

subject?: string | null
threat_categories?: Array<string> | null
to?: Array<string> | null
to_name?: Array<string> | null
validation?: Validation | null
comment?: string | null
dkim?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf?: "pass" | "neutral" | "fail" | 2 more | null
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"

Search email messages

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiEmail: process.env['CLOUDFLARE_EMAIL'], // This is the default and can be omitted
  apiKey: process.env['CLOUDFLARE_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const investigateListResponse of client.emailSecurity.investigate.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(investigateListResponse.id);
}
{
  "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
}