Search email messages

client.EmailSecurity.Investigate.List(ctx, params) (*V4PagePaginationArray[InvestigateListResponse], error)

GET/accounts/{account_id}/email-security/investigate

Returns information for each email that matches the search parameter(s).

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

params InvestigateListParams

AccountID param.Field[string]

Path param: Identifier.

maxLength32

ActionLog param.Field[bool]Optional

Query param: Whether to include the message action log in the response.

AlertID param.Field[string]Optional

Query param

Cursor param.Field[string]Optional

Query param

DetectionsOnly param.Field[bool]Optional

Query param: Whether to include only detections in search results.

Domain param.Field[string]Optional

Query param: Sender domains to filter by.

End param.Field[Time]Optional

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

formatdate-time

FinalDisposition param.Field[InvestigateListParamsFinalDisposition]Optional

Query param: Dispositions to filter by.

const InvestigateListParamsFinalDispositionMalicious InvestigateListParamsFinalDisposition = "MALICIOUS"

const InvestigateListParamsFinalDispositionSuspicious InvestigateListParamsFinalDisposition = "SUSPICIOUS"

const InvestigateListParamsFinalDispositionSpoof InvestigateListParamsFinalDisposition = "SPOOF"

const InvestigateListParamsFinalDispositionSpam InvestigateListParamsFinalDisposition = "SPAM"

const InvestigateListParamsFinalDispositionBulk InvestigateListParamsFinalDisposition = "BULK"

const InvestigateListParamsFinalDispositionNone InvestigateListParamsFinalDisposition = "NONE"

MessageAction param.Field[InvestigateListParamsMessageAction]Optional

Query param: Message actions to filter by.

const InvestigateListParamsMessageActionPreview InvestigateListParamsMessageAction = "PREVIEW"

const InvestigateListParamsMessageActionQuarantineReleased InvestigateListParamsMessageAction = "QUARANTINE_RELEASED"

const InvestigateListParamsMessageActionMoved InvestigateListParamsMessageAction = "MOVED"

MessageID param.Field[string]Optional

Query param

Metric param.Field[string]Optional

Query param

Page param.Field[int64]Optional

Query param: Deprecated: Use cursor pagination instead. End of life: November 1, 2026.

minimum1

PerPage param.Field[int64]Optional

Query param: The number of results per page. Maximum value is 1000.

maximum1000

minimum1

Query param.Field[string]Optional

Query param: Space-delimited search term. Case-insensitive.

Recipient param.Field[string]Optional

Query param

Sender param.Field[string]Optional

Query param

Start param.Field[Time]Optional

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

formatdate-time

Subject param.Field[string]Optional

Query param

ReturnsExpand Collapse

type InvestigateListResponse struct{…}

ID string

Unique identifier for a message retrieved from investigation

DeprecatedActionLog []InvestigateListResponseActionLog

Deprecated, use GET /investigate/{investigate_id}/action_log instead. End of life: November 1, 2026.

CompletedAt Time

Timestamp when action completed

formatdate-time

Operation InvestigateListResponseActionLogOperation

Type of action performed

One of the following:

const InvestigateListResponseActionLogOperationMove InvestigateListResponseActionLogOperation = "MOVE"

const InvestigateListResponseActionLogOperationRelease InvestigateListResponseActionLogOperation = "RELEASE"

const InvestigateListResponseActionLogOperationReclassify InvestigateListResponseActionLogOperation = "RECLASSIFY"

const InvestigateListResponseActionLogOperationSubmission InvestigateListResponseActionLogOperation = "SUBMISSION"

const InvestigateListResponseActionLogOperationQuarantineRelease InvestigateListResponseActionLogOperation = "QUARANTINE_RELEASE"

const InvestigateListResponseActionLogOperationPreview InvestigateListResponseActionLogOperation = "PREVIEW"

DeprecatedCompletedTimestamp stringOptional

Deprecated, use completed_at instead. End of life: November 1, 2026.

Properties InvestigateListResponseActionLogPropertiesOptional

Additional properties for the action

Folder stringOptional

Target folder for move operations

RequestedBy stringOptional

User who requested the action

Status stringOptional

Status of the action

ClientRecipients []string

DetectionReasons []string

IsPhishSubmission bool

IsQuarantined bool

PostfixID string

The identifier of the message

Properties InvestigateListResponseProperties

Message processing properties

AllowlistedPattern stringOptional

Pattern that allowlisted this message

AllowlistedPatternType InvestigateListResponsePropertiesAllowlistedPatternTypeOptional

Type of allowlist pattern

One of the following:

const InvestigateListResponsePropertiesAllowlistedPatternTypeQuarantineRelease InvestigateListResponsePropertiesAllowlistedPatternType = "quarantine_release"

const InvestigateListResponsePropertiesAllowlistedPatternTypeAcceptableSender InvestigateListResponsePropertiesAllowlistedPatternType = "acceptable_sender"

const InvestigateListResponsePropertiesAllowlistedPatternTypeAllowedSender InvestigateListResponsePropertiesAllowlistedPatternType = "allowed_sender"

const InvestigateListResponsePropertiesAllowlistedPatternTypeAllowedRecipient InvestigateListResponsePropertiesAllowlistedPatternType = "allowed_recipient"

const InvestigateListResponsePropertiesAllowlistedPatternTypeDomainSimilarity InvestigateListResponsePropertiesAllowlistedPatternType = "domain_similarity"

const InvestigateListResponsePropertiesAllowlistedPatternTypeDomainRecency InvestigateListResponsePropertiesAllowlistedPatternType = "domain_recency"

const InvestigateListResponsePropertiesAllowlistedPatternTypeManagedAcceptableSender InvestigateListResponsePropertiesAllowlistedPatternType = "managed_acceptable_sender"

const InvestigateListResponsePropertiesAllowlistedPatternTypeOutboundNdr InvestigateListResponsePropertiesAllowlistedPatternType = "outbound_ndr"

BlocklistedMessage boolOptional

Whether message was blocklisted

BlocklistedPattern stringOptional

Pattern that blocklisted this message

WhitelistedPatternType InvestigateListResponsePropertiesWhitelistedPatternTypeOptional

Legacy field for allowlist pattern type

One of the following:

const InvestigateListResponsePropertiesWhitelistedPatternTypeQuarantineRelease InvestigateListResponsePropertiesWhitelistedPatternType = "quarantine_release"

const InvestigateListResponsePropertiesWhitelistedPatternTypeAcceptableSender InvestigateListResponsePropertiesWhitelistedPatternType = "acceptable_sender"

const InvestigateListResponsePropertiesWhitelistedPatternTypeAllowedSender InvestigateListResponsePropertiesWhitelistedPatternType = "allowed_sender"

const InvestigateListResponsePropertiesWhitelistedPatternTypeAllowedRecipient InvestigateListResponsePropertiesWhitelistedPatternType = "allowed_recipient"

const InvestigateListResponsePropertiesWhitelistedPatternTypeDomainSimilarity InvestigateListResponsePropertiesWhitelistedPatternType = "domain_similarity"

const InvestigateListResponsePropertiesWhitelistedPatternTypeDomainRecency InvestigateListResponsePropertiesWhitelistedPatternType = "domain_recency"

const InvestigateListResponsePropertiesWhitelistedPatternTypeManagedAcceptableSender InvestigateListResponsePropertiesWhitelistedPatternType = "managed_acceptable_sender"

const InvestigateListResponsePropertiesWhitelistedPatternTypeOutboundNdr InvestigateListResponsePropertiesWhitelistedPatternType = "outbound_ndr"

DeprecatedTs string

Deprecated, use scanned_at instead. End of life: November 1, 2026.

AlertID stringOptional

DeliveryMode InvestigateListResponseDeliveryModeOptional

One of the following:

const InvestigateListResponseDeliveryModeDirect InvestigateListResponseDeliveryMode = "DIRECT"

const InvestigateListResponseDeliveryModeBcc InvestigateListResponseDeliveryMode = "BCC"

const InvestigateListResponseDeliveryModeJournal InvestigateListResponseDeliveryMode = "JOURNAL"

const InvestigateListResponseDeliveryModeReviewSubmission InvestigateListResponseDeliveryMode = "REVIEW_SUBMISSION"

const InvestigateListResponseDeliveryModeDMARCUnverified InvestigateListResponseDeliveryMode = "DMARC_UNVERIFIED"

const InvestigateListResponseDeliveryModeDMARCFailureReport InvestigateListResponseDeliveryMode = "DMARC_FAILURE_REPORT"

const InvestigateListResponseDeliveryModeDMARCAggregateReport InvestigateListResponseDeliveryMode = "DMARC_AGGREGATE_REPORT"

const InvestigateListResponseDeliveryModeThreatIntelSubmission InvestigateListResponseDeliveryMode = "THREAT_INTEL_SUBMISSION"

const InvestigateListResponseDeliveryModeSimulationSubmission InvestigateListResponseDeliveryMode = "SIMULATION_SUBMISSION"

const InvestigateListResponseDeliveryModeAPI InvestigateListResponseDeliveryMode = "API"

const InvestigateListResponseDeliveryModeRetroScan InvestigateListResponseDeliveryMode = "RETRO_SCAN"

DeliveryStatus []InvestigateListResponseDeliveryStatusOptional

One of the following:

const InvestigateListResponseDeliveryStatusDelivered InvestigateListResponseDeliveryStatus = "delivered"

const InvestigateListResponseDeliveryStatusMoved InvestigateListResponseDeliveryStatus = "moved"

const InvestigateListResponseDeliveryStatusQuarantined InvestigateListResponseDeliveryStatus = "quarantined"

const InvestigateListResponseDeliveryStatusRejected InvestigateListResponseDeliveryStatus = "rejected"

const InvestigateListResponseDeliveryStatusDeferred InvestigateListResponseDeliveryStatus = "deferred"

const InvestigateListResponseDeliveryStatusBounced InvestigateListResponseDeliveryStatus = "bounced"

const InvestigateListResponseDeliveryStatusQueued InvestigateListResponseDeliveryStatus = "queued"

EdfHash stringOptional

EnvelopeFrom stringOptional

EnvelopeTo []stringOptional

FinalDisposition InvestigateListResponseFinalDispositionOptional

One of the following:

const InvestigateListResponseFinalDispositionMalicious InvestigateListResponseFinalDisposition = "MALICIOUS"

const InvestigateListResponseFinalDispositionMaliciousBec InvestigateListResponseFinalDisposition = "MALICIOUS-BEC"

const InvestigateListResponseFinalDispositionSuspicious InvestigateListResponseFinalDisposition = "SUSPICIOUS"

const InvestigateListResponseFinalDispositionSpoof InvestigateListResponseFinalDisposition = "SPOOF"

const InvestigateListResponseFinalDispositionSpam InvestigateListResponseFinalDisposition = "SPAM"

const InvestigateListResponseFinalDispositionBulk InvestigateListResponseFinalDisposition = "BULK"

const InvestigateListResponseFinalDispositionEncrypted InvestigateListResponseFinalDisposition = "ENCRYPTED"

const InvestigateListResponseFinalDispositionExternal InvestigateListResponseFinalDisposition = "EXTERNAL"

const InvestigateListResponseFinalDispositionUnknown InvestigateListResponseFinalDisposition = "UNKNOWN"

const InvestigateListResponseFinalDispositionNone InvestigateListResponseFinalDisposition = "NONE"

DeprecatedFindings []InvestigateListResponseFindingOptional

Deprecated, use the findings field from GET /investigate/{investigate_id}/detections instead. End of life: November 1, 2026. Detection findings for this message.

Attachment stringOptional

Detail stringOptional

Detection InvestigateListResponseFindingsDetectionOptional

One of the following:

const InvestigateListResponseFindingsDetectionMalicious InvestigateListResponseFindingsDetection = "MALICIOUS"

const InvestigateListResponseFindingsDetectionMaliciousBec InvestigateListResponseFindingsDetection = "MALICIOUS-BEC"

const InvestigateListResponseFindingsDetectionSuspicious InvestigateListResponseFindingsDetection = "SUSPICIOUS"

const InvestigateListResponseFindingsDetectionSpoof InvestigateListResponseFindingsDetection = "SPOOF"

const InvestigateListResponseFindingsDetectionSpam InvestigateListResponseFindingsDetection = "SPAM"

const InvestigateListResponseFindingsDetectionBulk InvestigateListResponseFindingsDetection = "BULK"

const InvestigateListResponseFindingsDetectionEncrypted InvestigateListResponseFindingsDetection = "ENCRYPTED"

const InvestigateListResponseFindingsDetectionExternal InvestigateListResponseFindingsDetection = "EXTERNAL"

const InvestigateListResponseFindingsDetectionUnknown InvestigateListResponseFindingsDetection = "UNKNOWN"

const InvestigateListResponseFindingsDetectionNone InvestigateListResponseFindingsDetection = "NONE"

Field stringOptional

Name stringOptional

Portion stringOptional

Reason stringOptional

Score float64Optional

formatdouble

Value stringOptional

From stringOptional

FromName stringOptional

HtmltextStructureHash stringOptional

MessageID stringOptional

PostDeliveryOperations []InvestigateListResponsePostDeliveryOperationOptional

Post-delivery operations performed on this message

One of the following:

const InvestigateListResponsePostDeliveryOperationPreview InvestigateListResponsePostDeliveryOperation = "PREVIEW"

const InvestigateListResponsePostDeliveryOperationQuarantineRelease InvestigateListResponsePostDeliveryOperation = "QUARANTINE_RELEASE"

const InvestigateListResponsePostDeliveryOperationSubmission InvestigateListResponsePostDeliveryOperation = "SUBMISSION"

const InvestigateListResponsePostDeliveryOperationMove InvestigateListResponsePostDeliveryOperation = "MOVE"

PostfixIDOutbound stringOptional

Replyto stringOptional

ScannedAt TimeOptional

When the message was scanned (UTC)

formatdate-time

SentAt TimeOptional

When the message was sent (UTC)

formatdate-time

SentDate stringOptional

Subject stringOptional

ThreatCategories []stringOptional

To []stringOptional

ToName []stringOptional

Validation InvestigateListResponseValidationOptional

Comment stringOptional

DKIM InvestigateListResponseValidationDKIMOptional

One of the following:

const InvestigateListResponseValidationDKIMPass InvestigateListResponseValidationDKIM = "pass"

const InvestigateListResponseValidationDKIMNeutral InvestigateListResponseValidationDKIM = "neutral"

const InvestigateListResponseValidationDKIMFail InvestigateListResponseValidationDKIM = "fail"

const InvestigateListResponseValidationDKIMError InvestigateListResponseValidationDKIM = "error"

const InvestigateListResponseValidationDKIMNone InvestigateListResponseValidationDKIM = "none"

DMARC InvestigateListResponseValidationDMARCOptional

One of the following:

const InvestigateListResponseValidationDMARCPass InvestigateListResponseValidationDMARC = "pass"

const InvestigateListResponseValidationDMARCNeutral InvestigateListResponseValidationDMARC = "neutral"

const InvestigateListResponseValidationDMARCFail InvestigateListResponseValidationDMARC = "fail"

const InvestigateListResponseValidationDMARCError InvestigateListResponseValidationDMARC = "error"

const InvestigateListResponseValidationDMARCNone InvestigateListResponseValidationDMARC = "none"

SPF InvestigateListResponseValidationSPFOptional

One of the following:

const InvestigateListResponseValidationSPFPass InvestigateListResponseValidationSPF = "pass"

const InvestigateListResponseValidationSPFNeutral InvestigateListResponseValidationSPF = "neutral"

const InvestigateListResponseValidationSPFFail InvestigateListResponseValidationSPF = "fail"

const InvestigateListResponseValidationSPFError InvestigateListResponseValidationSPF = "error"

const InvestigateListResponseValidationSPFNone InvestigateListResponseValidationSPF = "none"

Search email messages

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/email_security"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  page, err := client.EmailSecurity.Investigate.List(context.TODO(), email_security.InvestigateListParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

{
  "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-2024-01-05T10:00:00-12345678",
      "action_log": [
        {
          "completed_at": "2019-12-27T18:11:19.117Z",
          "operation": "MOVE",
          "completed_timestamp": "completed_timestamp",
          "properties": {
            "folder": "folder",
            "requested_by": "requested_by"
          },
          "status": "status"
        }
      ],
      "client_recipients": [
        "string"
      ],
      "detection_reasons": [
        "string"
      ],
      "is_phish_submission": true,
      "is_quarantined": true,
      "postfix_id": "4Njp3P0STMz2c02Q",
      "properties": {
        "allowlisted_pattern": "allowlisted_pattern",
        "allowlisted_pattern_type": "quarantine_release",
        "blocklisted_message": true,
        "blocklisted_pattern": "blocklisted_pattern",
        "whitelisted_pattern_type": "quarantine_release"
      },
      "ts": "ts",
      "alert_id": "alert_id",
      "delivery_mode": "DIRECT",
      "delivery_status": [
        "delivered"
      ],
      "edf_hash": "edf_hash",
      "envelope_from": "envelope_from",
      "envelope_to": [
        "string"
      ],
      "final_disposition": "MALICIOUS",
      "findings": [
        {
          "attachment": "attachment",
          "detail": "detail",
          "detection": "MALICIOUS",
          "field": "field",
          "name": "name",
          "portion": "portion",
          "reason": "reason",
          "score": 0,
          "value": "value"
        }
      ],
      "from": "from",
      "from_name": "from_name",
      "htmltext_structure_hash": "htmltext_structure_hash",
      "message_id": "message_id",
      "post_delivery_operations": [
        "PREVIEW"
      ],
      "postfix_id_outbound": "postfix_id_outbound",
      "replyto": "replyto",
      "scanned_at": "2019-12-27T18:11:19.117Z",
      "sent_at": "2019-12-27T18:11:19.117Z",
      "sent_date": "sent_date",
      "subject": "subject",
      "threat_categories": [
        "string"
      ],
      "to": [
        "string"
      ],
      "to_name": [
        "string"
      ],
      "validation": {
        "comment": "comment",
        "dkim": "pass",
        "dmarc": "pass",
        "spf": "pass"
      }
    }
  ],
  "result_info": {
    "count": 0,
    "per_page": 0,
    "total_count": 0,
    "next": "next",
    "page": 0,
    "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-2024-01-05T10:00:00-12345678",
      "action_log": [
        {
          "completed_at": "2019-12-27T18:11:19.117Z",
          "operation": "MOVE",
          "completed_timestamp": "completed_timestamp",
          "properties": {
            "folder": "folder",
            "requested_by": "requested_by"
          },
          "status": "status"
        }
      ],
      "client_recipients": [
        "string"
      ],
      "detection_reasons": [
        "string"
      ],
      "is_phish_submission": true,
      "is_quarantined": true,
      "postfix_id": "4Njp3P0STMz2c02Q",
      "properties": {
        "allowlisted_pattern": "allowlisted_pattern",
        "allowlisted_pattern_type": "quarantine_release",
        "blocklisted_message": true,
        "blocklisted_pattern": "blocklisted_pattern",
        "whitelisted_pattern_type": "quarantine_release"
      },
      "ts": "ts",
      "alert_id": "alert_id",
      "delivery_mode": "DIRECT",
      "delivery_status": [
        "delivered"
      ],
      "edf_hash": "edf_hash",
      "envelope_from": "envelope_from",
      "envelope_to": [
        "string"
      ],
      "final_disposition": "MALICIOUS",
      "findings": [
        {
          "attachment": "attachment",
          "detail": "detail",
          "detection": "MALICIOUS",
          "field": "field",
          "name": "name",
          "portion": "portion",
          "reason": "reason",
          "score": 0,
          "value": "value"
        }
      ],
      "from": "from",
      "from_name": "from_name",
      "htmltext_structure_hash": "htmltext_structure_hash",
      "message_id": "message_id",
      "post_delivery_operations": [
        "PREVIEW"
      ],
      "postfix_id_outbound": "postfix_id_outbound",
      "replyto": "replyto",
      "scanned_at": "2019-12-27T18:11:19.117Z",
      "sent_at": "2019-12-27T18:11:19.117Z",
      "sent_date": "sent_date",
      "subject": "subject",
      "threat_categories": [
        "string"
      ],
      "to": [
        "string"
      ],
      "to_name": [
        "string"
      ],
      "validation": {
        "comment": "comment",
        "dkim": "pass",
        "dmarc": "pass",
        "spf": "pass"
      }
    }
  ],
  "result_info": {
    "count": 0,
    "per_page": 0,
    "total_count": 0,
    "next": "next",
    "page": 0,
    "previous": "previous"
  },
  "success": true
}