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

Get message details

email_security.investigate.get(strpostfix_id, InvestigateGetParams**kwargs) -> InvestigateGetResponse
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
account_id: str

Account Identifier

maxLength32
minLength32
postfix_id: str

The identifier of the message.

ReturnsExpand Collapse
class InvestigateGetResponse: …
id: str
action_log: object
client_recipients: List[str]
detection_reasons: List[str]
is_phish_submission: bool
is_quarantined: bool
postfix_id: str

The identifier of the message.

properties: Properties
allowlisted_pattern: Optional[str]
allowlisted_pattern_type: Optional[Literal["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: Optional[bool]
blocklisted_pattern: Optional[str]
whitelisted_pattern_type: Optional[Literal["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: str

Deprecated, use scanned_at instead

alert_id: Optional[str]
delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 8 more]]
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: Optional[str]
envelope_from: Optional[str]
envelope_to: Optional[List[str]]
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"
findings: Optional[List[Finding]]
attachment: Optional[str]
detail: 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"
field: Optional[str]
name: Optional[str]
portion: Optional[str]
reason: Optional[str]
score: Optional[float]
formatdouble
value: Optional[str]
from_: Optional[str]
from_name: Optional[str]
htmltext_structure_hash: Optional[str]
message_id: Optional[str]
post_delivery_operations: Optional[List[Literal["PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE"]]]
One of the following:
"PREVIEW"
"QUARANTINE_RELEASE"
"SUBMISSION"
"MOVE"
postfix_id_outbound: Optional[str]
replyto: Optional[str]
scanned_at: Optional[datetime]
formatdate-time
sent_at: Optional[datetime]
formatdate-time
Deprecatedsent_date: Optional[str]

Deprecated, use sent_at instead

subject: Optional[str]
threat_categories: Optional[List[str]]
to: Optional[List[str]]
to_name: Optional[List[str]]
validation: Optional[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"

Get message 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
)
investigate = client.email_security.investigate.get(
    postfix_id="4Njp3P0STMz2c02Q",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(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
}