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

Get message detection details

email_security.investigate.detections.get(strpostfix_id, DetectionGetParams**kwargs) -> DetectionGetResponse
GET/accounts/{account_id}/email-security/investigate/{postfix_id}/detections

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

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
account_id: str

Account Identifier

maxLength32
minLength32
postfix_id: str

The identifier of the message.

ReturnsExpand Collapse
class DetectionGetResponse: …
action: str
attachments: List[Attachment]
size: int
minimum0
content_type: Optional[str]
detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
encrypted: Optional[bool]
name: Optional[str]
headers: List[Header]
name: str
value: str
text: Optional[str]
sender_info: SenderInfo
as_name: Optional[str]

The name of the autonomous system.

as_number: Optional[int]

The number of the autonomous system.

formatint64
geo: Optional[str]
ip: Optional[str]
pld: Optional[str]
threat_categories: List[ThreatCategory]
id: int
formatint64
description: Optional[str]
name: Optional[str]
validation: Validation
comment: Optional[str]
dkim: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
spf: Optional[Literal["pass", "neutral", "fail", 2 more]]
One of the following:
"pass"
"neutral"
"fail"
"error"
"none"
final_disposition: Optional[Literal["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 os
from cloudflare import Cloudflare

client = Cloudflare(
    api_email=os.environ.get("CLOUDFLARE_EMAIL"),  # This is the default and can be omitted
    api_key=os.environ.get("CLOUDFLARE_API_KEY"),  # This is the default and can be omitted
)
detection = client.email_security.investigate.detections.get(
    postfix_id="4Njp3P0STMz2c02Q",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(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": "QUARANTINED",
    "attachments": [
      {
        "size": 0,
        "content_type": "content_type",
        "detection": "MALICIOUS",
        "encrypted": true,
        "name": "name"
      }
    ],
    "headers": [
      {
        "name": "From",
        "value": "Sender Name <d1994@example.com>"
      },
      {
        "name": "Subject",
        "value": "listen, I highly recommend u to read that email, just to ensure not a thing will take place"
      }
    ],
    "links": [
      {
        "href": "https://example.com",
        "text": "Click here!"
      }
    ],
    "sender_info": {
      "as_name": "AS0",
      "as_number": 0,
      "geo": "US/-/-",
      "ip": "127.0.0.1",
      "pld": "example.com"
    },
    "threat_categories": [
      {
        "id": 1234,
        "description": null,
        "name": "IP Reputation"
      }
    ],
    "validation": {
      "comment": null,
      "dkim": "pass",
      "dmarc": "none",
      "spf": "fail"
    },
    "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": "QUARANTINED",
    "attachments": [
      {
        "size": 0,
        "content_type": "content_type",
        "detection": "MALICIOUS",
        "encrypted": true,
        "name": "name"
      }
    ],
    "headers": [
      {
        "name": "From",
        "value": "Sender Name <d1994@example.com>"
      },
      {
        "name": "Subject",
        "value": "listen, I highly recommend u to read that email, just to ensure not a thing will take place"
      }
    ],
    "links": [
      {
        "href": "https://example.com",
        "text": "Click here!"
      }
    ],
    "sender_info": {
      "as_name": "AS0",
      "as_number": 0,
      "geo": "US/-/-",
      "ip": "127.0.0.1",
      "pld": "example.com"
    },
    "threat_categories": [
      {
        "id": 1234,
        "description": null,
        "name": "IP Reputation"
      }
    ],
    "validation": {
      "comment": null,
      "dkim": "pass",
      "dmarc": "none",
      "spf": "fail"
    },
    "final_disposition": "MALICIOUS"
  },
  "success": true
}