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

Get message detection details

client.emailSecurity.investigate.detections.get(stringinvestigateId, DetectionGetParams { account_id } params, RequestOptionsoptions?): DetectionGetResponse { action, attachments, findings, 6 more }
GET/accounts/{account_id}/email-security/investigate/{investigate_id}/detections

Returns detection details such as threat categories and sender information for non-benign messages.

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: WriteCloud Email Security: Read
ParametersExpand Collapse
investigateId: string

Unique identifier for a message retrieved from investigation

params: DetectionGetParams { account_id }
account_id: string

Identifier.

maxLength32
ReturnsExpand Collapse
DetectionGetResponse { action, attachments, findings, 6 more }
action: string
attachments: Array<Attachment>
size: number

Size of the attachment in bytes

minimum0
content_type?: string | null

MIME type of the attachment

detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null

Detection result for this attachment

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
encrypted?: boolean | null

Whether the attachment is encrypted

filename?: string | null

Name of the attached file

md5?: string | null

MD5 hash of the attachment

name?: string | null

Attachment name (alternative to filename)

sha1?: string | null

SHA1 hash of the attachment

sha256?: string | null

SHA256 hash of the attachment

findings: Array<Finding> | null
attachment?: string | null
detail?: string | null
detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more
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
headers: Array<Header>
name: string
value: string
text?: string | null
sender_info: SenderInfo { as_name, as_number, geo, 2 more }
as_name?: string | null

The name of the autonomous system.

as_number?: number | null

The number of the autonomous system.

geo?: string | null
ip?: string | null
pld?: string | null
threat_categories: Array<ThreatCategory>
id?: number
description?: string | null
name?: string | null
validation: Validation { comment, dkim, dmarc, spf }
comment?: string | null
dkim?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf?: "pass" | "neutral" | "fail" | 2 more
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"

Get message detection details

import Cloudflare from 'cloudflare';

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

const detection = await client.emailSecurity.investigate.detections.get(
  '4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

console.log(detection.validation);
{
  "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": {
    "action": "action",
    "attachments": [
      {
        "size": 0,
        "content_type": "content_type",
        "detection": "MALICIOUS",
        "encrypted": true,
        "filename": "filename",
        "md5": "md5",
        "name": "name",
        "sha1": "sha1",
        "sha256": "sha256"
      }
    ],
    "findings": [
      {
        "attachment": "attachment",
        "detail": "detail",
        "detection": "MALICIOUS",
        "field": "field",
        "name": "name",
        "portion": "portion",
        "reason": "reason",
        "score": 0,
        "value": "value"
      }
    ],
    "headers": [
      {
        "name": "name",
        "value": "value"
      }
    ],
    "links": [
      {
        "href": "href",
        "text": "text"
      }
    ],
    "sender_info": {
      "as_name": "as_name",
      "as_number": 0,
      "geo": "geo",
      "ip": "ip",
      "pld": "pld"
    },
    "threat_categories": [
      {
        "id": 0,
        "description": "description",
        "name": "name"
      }
    ],
    "validation": {
      "comment": "comment",
      "dkim": "pass",
      "dmarc": "pass",
      "spf": "pass"
    },
    "final_disposition": "MALICIOUS"
  },
  "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": {
    "action": "action",
    "attachments": [
      {
        "size": 0,
        "content_type": "content_type",
        "detection": "MALICIOUS",
        "encrypted": true,
        "filename": "filename",
        "md5": "md5",
        "name": "name",
        "sha1": "sha1",
        "sha256": "sha256"
      }
    ],
    "findings": [
      {
        "attachment": "attachment",
        "detail": "detail",
        "detection": "MALICIOUS",
        "field": "field",
        "name": "name",
        "portion": "portion",
        "reason": "reason",
        "score": 0,
        "value": "value"
      }
    ],
    "headers": [
      {
        "name": "name",
        "value": "value"
      }
    ],
    "links": [
      {
        "href": "href",
        "text": "text"
      }
    ],
    "sender_info": {
      "as_name": "as_name",
      "as_number": 0,
      "geo": "geo",
      "ip": "ip",
      "pld": "pld"
    },
    "threat_categories": [
      {
        "id": 0,
        "description": "description",
        "name": "name"
      }
    ],
    "validation": {
      "comment": "comment",
      "dkim": "pass",
      "dmarc": "pass",
      "spf": "pass"
    },
    "final_disposition": "MALICIOUS"
  },
  "success": true
}