## Search email messages `client.emailSecurity.investigate.list(InvestigateListParamsparams, RequestOptionsoptions?): V4PagePaginationArray` **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` - `account_id: string` Path param: Account Identifier - `action_log?: boolean` Query param: Determines if the message action log is included in the response. - `alert_id?: string` Query param - `cursor?: string` Query param - `detections_only?: boolean` Query param: Determines if the search results will include detections or not. - `domain?: string` Query param: Filter by a domain found in the email: sender domain, recipient domain, or a domain in a link. - `end?: string` Query param: The end of the search date range. Defaults to `now` if not provided. - `exact_subject?: string` Query param: Search for messages with an exact subject match. - `final_disposition?: "MALICIOUS" | "SUSPICIOUS" | "SPOOF" | 3 more` Query param: The dispositions the search filters by. - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `message_action?: "PREVIEW" | "QUARANTINE_RELEASED" | "MOVED" | "SUBMITTED"` Query param: The message actions the search filters by. - `"PREVIEW"` - `"QUARANTINE_RELEASED"` - `"MOVED"` - `"SUBMITTED"` - `message_id?: string` Query param - `metric?: string` Query param - `page?: number | null` Query param: Deprecated: Use cursor pagination instead. - `per_page?: number` Query param: The number of results per page. - `query?: 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?: string` Query param: Filter by recipient. Matches either an email address or a domain. - `sender?: string` Query param: Filter by sender. Matches either an email address or a domain. - `start?: string` Query param: The beginning of the search date range. Defaults to `now - 30 days` if not provided. - `subject?: string` Query param: Search for messages containing individual keywords in any order within the subject. - `submissions?: boolean` Query param: Search for submissions instead of original messages ### Returns - `InvestigateListResponse` - `id: string` - `action_log: unknown` - `client_recipients: Array` - `detection_reasons: Array` - `is_phish_submission: boolean` - `is_quarantined: boolean` - `postfix_id: string` The identifier of the message. - `properties: Properties` - `allowlisted_pattern?: string` - `allowlisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 5 more` - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `blocklisted_message?: boolean` - `blocklisted_pattern?: string` - `whitelisted_pattern_type?: "quarantine_release" | "acceptable_sender" | "allowed_sender" | 5 more` - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `ts: string` Deprecated, use `scanned_at` instead - `alert_id?: string | null` - `delivery_mode?: "DIRECT" | "BCC" | "JOURNAL" | 8 more | null` - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"REVIEW_SUBMISSION"` - `"DMARC_UNVERIFIED"` - `"DMARC_FAILURE_REPORT"` - `"DMARC_AGGREGATE_REPORT"` - `"THREAT_INTEL_SUBMISSION"` - `"SIMULATION_SUBMISSION"` - `"API"` - `"RETRO_SCAN"` - `edf_hash?: string | null` - `envelope_from?: string | null` - `envelope_to?: Array | null` - `final_disposition?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `findings?: Array | null` - `attachment?: string | null` - `detail?: string | null` - `detection?: "MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more | null` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `field?: string | null` - `name?: string | null` - `portion?: string | null` - `reason?: string | null` - `score?: number | null` - `value?: string | null` - `from?: string | null` - `from_name?: string | null` - `htmltext_structure_hash?: string | null` - `message_id?: string | null` - `post_delivery_operations?: Array<"PREVIEW" | "QUARANTINE_RELEASE" | "SUBMISSION" | "MOVE">` - `"PREVIEW"` - `"QUARANTINE_RELEASE"` - `"SUBMISSION"` - `"MOVE"` - `postfix_id_outbound?: string | null` - `replyto?: string | null` - `scanned_at?: string` - `sent_at?: string` - `sent_date?: string | null` Deprecated, use `sent_at` instead - `subject?: string | null` - `threat_categories?: Array | null` - `to?: Array | null` - `to_name?: Array | null` - `validation?: Validation | null` - `comment?: string | null` - `dkim?: "pass" | "neutral" | "fail" | 2 more | null` - `"pass"` - `"neutral"` - `"fail"` - `"error"` - `"none"` - `dmarc?: "pass" | "neutral" | "fail" | 2 more | null` - `"pass"` - `"neutral"` - `"fail"` - `"error"` - `"none"` - `spf?: "pass" | "neutral" | "fail" | 2 more | null` - `"pass"` - `"neutral"` - `"fail"` - `"error"` - `"none"` ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiEmail: process.env['CLOUDFLARE_EMAIL'], // This is the default and can be omitted apiKey: process.env['CLOUDFLARE_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const investigateListResponse of client.emailSecurity.investigate.list({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', })) { console.log(investigateListResponse.id); } ``` #### 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 } ```