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

Get message details

client.emailSecurity.investigate.get(stringpostfixId, InvestigateGetParams { account_id } params, RequestOptionsoptions?): InvestigateGetResponse { id, action_log, client_recipients, 28 more }
GET/accounts/{account_id}/email-security/investigate/{postfix_id}

Retrieves detailed information about a specific email message, including headers, metadata, and security scan results.

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
postfixId: string

The identifier of the message.

params: InvestigateGetParams { account_id }
account_id: string

Account Identifier

maxLength32
minLength32
ReturnsExpand Collapse
InvestigateGetResponse { 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"

Get message details

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
});

const investigate = await client.emailSecurity.investigate.get('4Njp3P0STMz2c02Q', {
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

console.log(investigate.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"
    }
  },
  "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"
    }
  },
  "success": true
}