## 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. ### Parameters - `params InvestigateListParams` - `AccountID param.Field[string]` Path param: Account Identifier - `ActionLog param.Field[bool]` Query param: Determines if the message action log is included in the response. - `AlertID param.Field[string]` Query param - `Cursor param.Field[string]` Query param - `DetectionsOnly param.Field[bool]` Query param: Determines if the search results will include detections or not. - `Domain param.Field[string]` Query param: Filter by a domain found in the email: sender domain, recipient domain, or a domain in a link. - `End param.Field[Time]` Query param: The end of the search date range. Defaults to `now` if not provided. - `ExactSubject param.Field[string]` Query param: Search for messages with an exact subject match. - `FinalDisposition param.Field[InvestigateListParamsFinalDisposition]` 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]` 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]` Query param - `Metric param.Field[string]` Query param - `Page param.Field[int64]` Query param: Deprecated: Use cursor pagination instead. - `PerPage param.Field[int64]` Query param: The number of results per page. - `Query param.Field[string]` 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]` Query param: Filter by recipient. Matches either an email address or a domain. - `Sender param.Field[string]` Query param: Filter by sender. Matches either an email address or a domain. - `Start param.Field[Time]` Query param: The beginning of the search date range. Defaults to `now - 30 days` if not provided. - `Subject param.Field[string]` Query param: Search for messages containing individual keywords in any order within the subject. - `Submissions param.Field[bool]` Query param: Search for submissions instead of original messages ### Returns - `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 string` - `AllowlistedPatternType InvestigateListResponsePropertiesAllowlistedPatternType` - `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 bool` - `BlocklistedPattern string` - `WhitelistedPatternType InvestigateListResponsePropertiesWhitelistedPatternType` - `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"` - `Ts string` Deprecated, use `scanned_at` instead - `AlertID string` - `DeliveryMode InvestigateListResponseDeliveryMode` - `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 string` - `EnvelopeFrom string` - `EnvelopeTo []string` - `FinalDisposition InvestigateListResponseFinalDisposition` - `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 []InvestigateListResponseFinding` - `Attachment string` - `Detail string` - `Detection InvestigateListResponseFindingsDetection` - `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 string` - `Name string` - `Portion string` - `Reason string` - `Score float64` - `Value string` - `From string` - `FromName string` - `HtmltextStructureHash string` - `MessageID string` - `PostDeliveryOperations []InvestigateListResponsePostDeliveryOperation` - `const InvestigateListResponsePostDeliveryOperationPreview InvestigateListResponsePostDeliveryOperation = "PREVIEW"` - `const InvestigateListResponsePostDeliveryOperationQuarantineRelease InvestigateListResponsePostDeliveryOperation = "QUARANTINE_RELEASE"` - `const InvestigateListResponsePostDeliveryOperationSubmission InvestigateListResponsePostDeliveryOperation = "SUBMISSION"` - `const InvestigateListResponsePostDeliveryOperationMove InvestigateListResponsePostDeliveryOperation = "MOVE"` - `PostfixIDOutbound string` - `Replyto string` - `ScannedAt Time` - `SentAt Time` - `SentDate string` Deprecated, use `sent_at` instead - `Subject string` - `ThreatCategories []string` - `To []string` - `ToName []string` - `Validation InvestigateListResponseValidation` - `Comment string` - `DKIM InvestigateListResponseValidationDKIM` - `const InvestigateListResponseValidationDKIMPass InvestigateListResponseValidationDKIM = "pass"` - `const InvestigateListResponseValidationDKIMNeutral InvestigateListResponseValidationDKIM = "neutral"` - `const InvestigateListResponseValidationDKIMFail InvestigateListResponseValidationDKIM = "fail"` - `const InvestigateListResponseValidationDKIMError InvestigateListResponseValidationDKIM = "error"` - `const InvestigateListResponseValidationDKIMNone InvestigateListResponseValidationDKIM = "none"` - `DMARC InvestigateListResponseValidationDMARC` - `const InvestigateListResponseValidationDMARCPass InvestigateListResponseValidationDMARC = "pass"` - `const InvestigateListResponseValidationDMARCNeutral InvestigateListResponseValidationDMARC = "neutral"` - `const InvestigateListResponseValidationDMARCFail InvestigateListResponseValidationDMARC = "fail"` - `const InvestigateListResponseValidationDMARCError InvestigateListResponseValidationDMARC = "error"` - `const InvestigateListResponseValidationDMARCNone InvestigateListResponseValidationDMARC = "none"` - `SPF InvestigateListResponseValidationSPF` - `const InvestigateListResponseValidationSPFPass InvestigateListResponseValidationSPF = "pass"` - `const InvestigateListResponseValidationSPFNeutral InvestigateListResponseValidationSPF = "neutral"` - `const InvestigateListResponseValidationSPFFail InvestigateListResponseValidationSPF = "fail"` - `const InvestigateListResponseValidationSPFError InvestigateListResponseValidationSPF = "error"` - `const InvestigateListResponseValidationSPFNone InvestigateListResponseValidationSPF = "none"` ### Example ```go 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) } ``` #### Response ```json { "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=127.0.0[dot]186" ], "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 } ```