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). If the search takes too long, the endpoint returns 202 with a Location header pointing to a polling endpoint where results can be retrieved once ready.

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

params InvestigateListParams

AccountID param.Field[string]

Path param: Account Identifier

maxLength32

minLength32

ActionLog param.Field[bool]optional

Query param: Determines if the message action log is included in the response.

AlertID param.Field[string]optional

Query param

Cursor param.Field[string]optional

Query param

DetectionsOnly param.Field[bool]optional

Query param: Determines if the search results will include detections or not.

Domain param.Field[string]optional

Query param: Filter by a domain found in the email: sender domain, recipient domain, or a domain in a link.

End param.Field[Time]optional

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

formatdate-time

ExactSubject param.Field[string]optional

Query param: Search for messages with an exact subject match.

FinalDisposition param.Field[InvestigateListParamsFinalDisposition]optional

Query param: The dispositions the search filters 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: The message actions the search filters by.

const InvestigateListParamsMessageActionPreview InvestigateListParamsMessageAction = "PREVIEW"

const InvestigateListParamsMessageActionQuarantineReleased InvestigateListParamsMessageAction = "QUARANTINE_RELEASED"

const InvestigateListParamsMessageActionMoved InvestigateListParamsMessageAction = "MOVED"

const InvestigateListParamsMessageActionSubmitted InvestigateListParamsMessageAction = "SUBMITTED"

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.

formatint32

minimum1

PerPage param.Field[int64]optional

Query param: The number of results per page.

formatint32

minimum1

Query param.Field[string]optional

Query param: The space-delimited term used in the query. The search is case-insensitive.

The content of the following email metadata fields are searched:

alert_id
CC
From (envelope_from)
From Name
final_disposition
md5 hash (of any attachment)
sha1 hash (of any attachment)
sha256 hash (of any attachment)
name (of any attachment)
Reason
Received DateTime (yyyy-mm-ddThh:mm:ss)
Sent DateTime (yyyy-mm-ddThh:mm:ss)
ReplyTo
To (envelope_to)
To Name
Message-ID
smtp_helo_server_ip
smtp_previous_hop_ip
x_originating_ip
Subject

Recipient param.Field[string]optional

Query param: Filter by recipient. Matches either an email address or a domain.

Sender param.Field[string]optional

Query param: Filter by sender. Matches either an email address or a domain.

Start param.Field[Time]optional

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

formatdate-time

Subject param.Field[string]optional

Query param: Search for messages containing individual keywords in any order within the subject.

Submissions param.Field[bool]optional

Query param: Search for submissions instead of original messages

ReturnsExpand Collapse

type InvestigateListResponse struct{…}

ID string

ActionLog unknown

ClientRecipients []string

DetectionReasons []string

IsPhishSubmission bool

IsQuarantined bool

PostfixID string

The identifier of the message.

Properties InvestigateListResponseProperties

AllowlistedPattern stringoptional

AllowlistedPatternType InvestigateListResponsePropertiesAllowlistedPatternTypeoptional

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

BlocklistedPattern stringoptional

WhitelistedPatternType InvestigateListResponsePropertiesWhitelistedPatternTypeoptional

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

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"

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"

Findings []InvestigateListResponseFindingoptional

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

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

formatdate-time

SentAt Timeoptional

formatdate-time

DeprecatedSentDate stringoptional

Deprecated, use sent_at instead

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.WithAPIKey("144c9defac04969c7bfad8efaa8ea194"),
    option.WithAPIEmail("user@example.com"),
  )
  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-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"
      }
    }
  ],
  "result_info": {
    "count": 0,
    "page": 0,
    "per_page": 0,
    "total_count": 0,
    "next": "next",
    "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-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"
      }
    }
  ],
  "result_info": {
    "count": 0,
    "page": 0,
    "per_page": 0,
    "total_count": 0,
    "next": "next",
    "previous": "previous"
  },
  "success": true
}