## Search email messages

`email_security.investigate.list(InvestigateListParams**kwargs)  -> SyncV4PagePaginationArray[InvestigateListResponse]`

**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

- `account_id: str`

  Account Identifier

- `action_log: Optional[bool]`

  Determines if the message action log is included in the response.

- `alert_id: Optional[str]`

- `cursor: Optional[str]`

- `detections_only: Optional[bool]`

  Determines if the search results will include detections or not.

- `domain: Optional[str]`

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

- `end: Optional[Union[str, datetime]]`

  The end of the search date range.
  Defaults to `now` if not provided.

- `exact_subject: Optional[str]`

  Search for messages with an exact subject match.

- `final_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]`

  The dispositions the search filters by.

  - `"MALICIOUS"`

  - `"SUSPICIOUS"`

  - `"SPOOF"`

  - `"SPAM"`

  - `"BULK"`

  - `"NONE"`

- `message_action: Optional[Literal["PREVIEW", "QUARANTINE_RELEASED", "MOVED", "SUBMITTED"]]`

  The message actions the search filters by.

  - `"PREVIEW"`

  - `"QUARANTINE_RELEASED"`

  - `"MOVED"`

  - `"SUBMITTED"`

- `message_id: Optional[str]`

- `metric: Optional[str]`

- `page: Optional[int]`

  Deprecated: Use cursor pagination instead.

- `per_page: Optional[int]`

  The number of results per page.

- `query: Optional[str]`

  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: Optional[str]`

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

- `sender: Optional[str]`

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

- `start: Optional[Union[str, datetime]]`

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

- `subject: Optional[str]`

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

- `submissions: Optional[bool]`

  Search for submissions instead of original messages

### Returns

- `class InvestigateListResponse: …`

  - `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]]`

      - `"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]]`

      - `"quarantine_release"`

      - `"acceptable_sender"`

      - `"allowed_sender"`

      - `"allowed_recipient"`

      - `"domain_similarity"`

      - `"domain_recency"`

      - `"managed_acceptable_sender"`

      - `"outbound_ndr"`

  - `ts: str`

    Deprecated, use `scanned_at` instead

  - `alert_id: Optional[str]`

  - `delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 8 more]]`

    - `"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]]`

    - `"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]]`

      - `"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]`

    - `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"]]]`

    - `"PREVIEW"`

    - `"QUARANTINE_RELEASE"`

    - `"SUBMISSION"`

    - `"MOVE"`

  - `postfix_id_outbound: Optional[str]`

  - `replyto: Optional[str]`

  - `scanned_at: Optional[datetime]`

  - `sent_at: Optional[datetime]`

  - `sent_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]]`

      - `"pass"`

      - `"neutral"`

      - `"fail"`

      - `"error"`

      - `"none"`

    - `dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]`

      - `"pass"`

      - `"neutral"`

      - `"fail"`

      - `"error"`

      - `"none"`

    - `spf: Optional[Literal["pass", "neutral", "fail", 2 more]]`

      - `"pass"`

      - `"neutral"`

      - `"fail"`

      - `"error"`

      - `"none"`

### Example

```python
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
)
page = client.email_security.investigate.list(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
page = page.result[0]
print(page.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=<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
}
```