# Email Security # Investigate ## 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). ### Parameters - `account_id: str` Identifier. - `action_log: Optional[bool]` Whether to include the message action log in the response. - `alert_id: Optional[str]` - `cursor: Optional[str]` - `detections_only: Optional[bool]` Whether to include only detections in search results. - `domain: Optional[str]` Sender domains to filter by. - `end: Optional[Union[str, datetime]]` The end of the search date range. Defaults to `now`. - `final_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` Dispositions to filter by. - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `message_action: Optional[Literal["PREVIEW", "QUARANTINE_RELEASED", "MOVED"]]` Message actions to filter by. - `"PREVIEW"` - `"QUARANTINE_RELEASED"` - `"MOVED"` - `message_id: Optional[str]` - `metric: Optional[str]` - `page: Optional[int]` Deprecated: Use cursor pagination instead. End of life: November 1, 2026. - `per_page: Optional[int]` The number of results per page. Maximum value is 1000. - `query: Optional[str]` Space-delimited search term. Case-insensitive. - `recipient: Optional[str]` - `sender: Optional[str]` - `start: Optional[Union[str, datetime]]` The beginning of the search date range. Defaults to `now - 30 days`. - `subject: Optional[str]` ### Returns - `class InvestigateListResponse: …` - `id: str` Unique identifier for a message retrieved from investigation - `action_log: List[ActionLog]` Deprecated, use `GET /investigate/{investigate_id}/action_log` instead. End of life: November 1, 2026. - `completed_at: datetime` Timestamp when action completed - `operation: Literal["MOVE", "RELEASE", "RECLASSIFY", 3 more]` Type of action performed - `"MOVE"` - `"RELEASE"` - `"RECLASSIFY"` - `"SUBMISSION"` - `"QUARANTINE_RELEASE"` - `"PREVIEW"` - `completed_timestamp: Optional[str]` Deprecated, use `completed_at` instead. End of life: November 1, 2026. - `properties: Optional[ActionLogProperties]` Additional properties for the action - `folder: Optional[str]` Target folder for move operations - `requested_by: Optional[str]` User who requested the action - `status: Optional[str]` Status of the action - `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` Message processing properties - `allowlisted_pattern: Optional[str]` Pattern that allowlisted this message - `allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]` Type of allowlist pattern - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `blocklisted_message: Optional[bool]` Whether message was blocklisted - `blocklisted_pattern: Optional[str]` Pattern that blocklisted this message - `whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]` Legacy field for allowlist pattern type - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `ts: str` Deprecated, use `scanned_at` instead. End of life: November 1, 2026. - `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"` - `delivery_status: Optional[List[Literal["delivered", "moved", "quarantined", 4 more]]]` - `"delivered"` - `"moved"` - `"quarantined"` - `"rejected"` - `"deferred"` - `"bounced"` - `"queued"` - `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]]` Deprecated, use the `findings` field from `GET /investigate/{investigate_id}/detections` instead. End of life: November 1, 2026. Detection findings for this message. - `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"]]]` Post-delivery operations performed on this message - `"PREVIEW"` - `"QUARANTINE_RELEASE"` - `"SUBMISSION"` - `"MOVE"` - `postfix_id_outbound: Optional[str]` - `replyto: Optional[str]` - `scanned_at: Optional[datetime]` When the message was scanned (UTC) - `sent_at: Optional[datetime]` When the message was sent (UTC) - `sent_date: Optional[str]` - `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_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # 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-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 } ``` ## Get message details `email_security.investigate.get(strinvestigate_id, InvestigateGetParams**kwargs) -> InvestigateGetResponse` **get** `/accounts/{account_id}/email-security/investigate/{investigate_id}` Retrieves comprehensive details for a specific email message including headers, recipients, sender information, and current quarantine status. Use the investigate_id from search results to fetch detailed information. ### Parameters - `account_id: str` Identifier. - `investigate_id: str` Unique identifier for a message retrieved from investigation - `submission: Optional[bool]` When true, search the submissions datastore only. When false or omitted, search the regular datastore only. ### Returns - `class InvestigateGetResponse: …` - `id: str` Unique identifier for a message retrieved from investigation - `action_log: List[ActionLog]` Deprecated, use `GET /investigate/{investigate_id}/action_log` instead. End of life: November 1, 2026. - `completed_at: datetime` Timestamp when action completed - `operation: Literal["MOVE", "RELEASE", "RECLASSIFY", 3 more]` Type of action performed - `"MOVE"` - `"RELEASE"` - `"RECLASSIFY"` - `"SUBMISSION"` - `"QUARANTINE_RELEASE"` - `"PREVIEW"` - `completed_timestamp: Optional[str]` Deprecated, use `completed_at` instead. End of life: November 1, 2026. - `properties: Optional[ActionLogProperties]` Additional properties for the action - `folder: Optional[str]` Target folder for move operations - `requested_by: Optional[str]` User who requested the action - `status: Optional[str]` Status of the action - `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` Message processing properties - `allowlisted_pattern: Optional[str]` Pattern that allowlisted this message - `allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]` Type of allowlist pattern - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `blocklisted_message: Optional[bool]` Whether message was blocklisted - `blocklisted_pattern: Optional[str]` Pattern that blocklisted this message - `whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]` Legacy field for allowlist pattern type - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `ts: str` Deprecated, use `scanned_at` instead. End of life: November 1, 2026. - `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"` - `delivery_status: Optional[List[Literal["delivered", "moved", "quarantined", 4 more]]]` - `"delivered"` - `"moved"` - `"quarantined"` - `"rejected"` - `"deferred"` - `"bounced"` - `"queued"` - `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]]` Deprecated, use the `findings` field from `GET /investigate/{investigate_id}/detections` instead. End of life: November 1, 2026. Detection findings for this message. - `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"]]]` Post-delivery operations performed on this message - `"PREVIEW"` - `"QUARANTINE_RELEASE"` - `"SUBMISSION"` - `"MOVE"` - `postfix_id_outbound: Optional[str]` - `replyto: Optional[str]` - `scanned_at: Optional[datetime]` When the message was scanned (UTC) - `sent_at: Optional[datetime]` When the message was sent (UTC) - `sent_date: Optional[str]` - `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_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) investigate = client.email_security.investigate.get( investigate_id="4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(investigate.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-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" } }, "success": true } ``` ## Domain Types ### Investigate List Response - `class InvestigateListResponse: …` - `id: str` Unique identifier for a message retrieved from investigation - `action_log: List[ActionLog]` Deprecated, use `GET /investigate/{investigate_id}/action_log` instead. End of life: November 1, 2026. - `completed_at: datetime` Timestamp when action completed - `operation: Literal["MOVE", "RELEASE", "RECLASSIFY", 3 more]` Type of action performed - `"MOVE"` - `"RELEASE"` - `"RECLASSIFY"` - `"SUBMISSION"` - `"QUARANTINE_RELEASE"` - `"PREVIEW"` - `completed_timestamp: Optional[str]` Deprecated, use `completed_at` instead. End of life: November 1, 2026. - `properties: Optional[ActionLogProperties]` Additional properties for the action - `folder: Optional[str]` Target folder for move operations - `requested_by: Optional[str]` User who requested the action - `status: Optional[str]` Status of the action - `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` Message processing properties - `allowlisted_pattern: Optional[str]` Pattern that allowlisted this message - `allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]` Type of allowlist pattern - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `blocklisted_message: Optional[bool]` Whether message was blocklisted - `blocklisted_pattern: Optional[str]` Pattern that blocklisted this message - `whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]` Legacy field for allowlist pattern type - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `ts: str` Deprecated, use `scanned_at` instead. End of life: November 1, 2026. - `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"` - `delivery_status: Optional[List[Literal["delivered", "moved", "quarantined", 4 more]]]` - `"delivered"` - `"moved"` - `"quarantined"` - `"rejected"` - `"deferred"` - `"bounced"` - `"queued"` - `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]]` Deprecated, use the `findings` field from `GET /investigate/{investigate_id}/detections` instead. End of life: November 1, 2026. Detection findings for this message. - `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"]]]` Post-delivery operations performed on this message - `"PREVIEW"` - `"QUARANTINE_RELEASE"` - `"SUBMISSION"` - `"MOVE"` - `postfix_id_outbound: Optional[str]` - `replyto: Optional[str]` - `scanned_at: Optional[datetime]` When the message was scanned (UTC) - `sent_at: Optional[datetime]` When the message was sent (UTC) - `sent_date: Optional[str]` - `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"` ### Investigate Get Response - `class InvestigateGetResponse: …` - `id: str` Unique identifier for a message retrieved from investigation - `action_log: List[ActionLog]` Deprecated, use `GET /investigate/{investigate_id}/action_log` instead. End of life: November 1, 2026. - `completed_at: datetime` Timestamp when action completed - `operation: Literal["MOVE", "RELEASE", "RECLASSIFY", 3 more]` Type of action performed - `"MOVE"` - `"RELEASE"` - `"RECLASSIFY"` - `"SUBMISSION"` - `"QUARANTINE_RELEASE"` - `"PREVIEW"` - `completed_timestamp: Optional[str]` Deprecated, use `completed_at` instead. End of life: November 1, 2026. - `properties: Optional[ActionLogProperties]` Additional properties for the action - `folder: Optional[str]` Target folder for move operations - `requested_by: Optional[str]` User who requested the action - `status: Optional[str]` Status of the action - `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` Message processing properties - `allowlisted_pattern: Optional[str]` Pattern that allowlisted this message - `allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]` Type of allowlist pattern - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `blocklisted_message: Optional[bool]` Whether message was blocklisted - `blocklisted_pattern: Optional[str]` Pattern that blocklisted this message - `whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]` Legacy field for allowlist pattern type - `"quarantine_release"` - `"acceptable_sender"` - `"allowed_sender"` - `"allowed_recipient"` - `"domain_similarity"` - `"domain_recency"` - `"managed_acceptable_sender"` - `"outbound_ndr"` - `ts: str` Deprecated, use `scanned_at` instead. End of life: November 1, 2026. - `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"` - `delivery_status: Optional[List[Literal["delivered", "moved", "quarantined", 4 more]]]` - `"delivered"` - `"moved"` - `"quarantined"` - `"rejected"` - `"deferred"` - `"bounced"` - `"queued"` - `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]]` Deprecated, use the `findings` field from `GET /investigate/{investigate_id}/detections` instead. End of life: November 1, 2026. Detection findings for this message. - `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"]]]` Post-delivery operations performed on this message - `"PREVIEW"` - `"QUARANTINE_RELEASE"` - `"SUBMISSION"` - `"MOVE"` - `postfix_id_outbound: Optional[str]` - `replyto: Optional[str]` - `scanned_at: Optional[datetime]` When the message was scanned (UTC) - `sent_at: Optional[datetime]` When the message was sent (UTC) - `sent_date: Optional[str]` - `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"` # Detections ## Get message detection details `email_security.investigate.detections.get(strinvestigate_id, DetectionGetParams**kwargs) -> DetectionGetResponse` **get** `/accounts/{account_id}/email-security/investigate/{investigate_id}/detections` Returns detection details such as threat categories and sender information for non-benign messages. ### Parameters - `account_id: str` Identifier. - `investigate_id: str` Unique identifier for a message retrieved from investigation ### Returns - `class DetectionGetResponse: …` - `action: str` - `attachments: List[Attachment]` - `size: int` Size of the attachment in bytes - `content_type: Optional[str]` MIME type of the attachment - `detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]` Detection result for this attachment - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `encrypted: Optional[bool]` Whether the attachment is encrypted - `filename: Optional[str]` Name of the attached file - `md5: Optional[str]` MD5 hash of the attachment - `name: Optional[str]` Attachment name (alternative to filename) - `sha1: Optional[str]` SHA1 hash of the attachment - `sha256: Optional[str]` SHA256 hash of the attachment - `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]` - `headers: List[Header]` - `name: str` - `value: str` - `links: List[Link]` - `href: str` - `text: Optional[str]` - `sender_info: SenderInfo` - `as_name: Optional[str]` The name of the autonomous system. - `as_number: Optional[int]` The number of the autonomous system. - `geo: Optional[str]` - `ip: Optional[str]` - `pld: Optional[str]` - `threat_categories: List[ThreatCategory]` - `id: Optional[int]` - `description: Optional[str]` - `name: Optional[str]` - `validation: 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"` - `final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) detection = client.email_security.investigate.detections.get( investigate_id="4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(detection.validation) ``` #### 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": { "action": "action", "attachments": [ { "size": 0, "content_type": "content_type", "detection": "MALICIOUS", "encrypted": true, "filename": "filename", "md5": "md5", "name": "name", "sha1": "sha1", "sha256": "sha256" } ], "findings": [ { "attachment": "attachment", "detail": "detail", "detection": "MALICIOUS", "field": "field", "name": "name", "portion": "portion", "reason": "reason", "score": 0, "value": "value" } ], "headers": [ { "name": "name", "value": "value" } ], "links": [ { "href": "href", "text": "text" } ], "sender_info": { "as_name": "as_name", "as_number": 0, "geo": "geo", "ip": "ip", "pld": "pld" }, "threat_categories": [ { "id": 0, "description": "description", "name": "name" } ], "validation": { "comment": "comment", "dkim": "pass", "dmarc": "pass", "spf": "pass" }, "final_disposition": "MALICIOUS" }, "success": true } ``` ## Domain Types ### Detection Get Response - `class DetectionGetResponse: …` - `action: str` - `attachments: List[Attachment]` - `size: int` Size of the attachment in bytes - `content_type: Optional[str]` MIME type of the attachment - `detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]` Detection result for this attachment - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `encrypted: Optional[bool]` Whether the attachment is encrypted - `filename: Optional[str]` Name of the attached file - `md5: Optional[str]` MD5 hash of the attachment - `name: Optional[str]` Attachment name (alternative to filename) - `sha1: Optional[str]` SHA1 hash of the attachment - `sha256: Optional[str]` SHA256 hash of the attachment - `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]` - `headers: List[Header]` - `name: str` - `value: str` - `links: List[Link]` - `href: str` - `text: Optional[str]` - `sender_info: SenderInfo` - `as_name: Optional[str]` The name of the autonomous system. - `as_number: Optional[int]` The number of the autonomous system. - `geo: Optional[str]` - `ip: Optional[str]` - `pld: Optional[str]` - `threat_categories: List[ThreatCategory]` - `id: Optional[int]` - `description: Optional[str]` - `name: Optional[str]` - `validation: 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"` - `final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` # Preview ## Get email preview `email_security.investigate.preview.get(strinvestigate_id, PreviewGetParams**kwargs) -> PreviewGetResponse` **get** `/accounts/{account_id}/email-security/investigate/{investigate_id}/preview` Returns a preview of the message body as a base64 encoded PNG image for non-benign messages. ### Parameters - `account_id: str` Identifier. - `investigate_id: str` Unique identifier for a message retrieved from investigation ### Returns - `class PreviewGetResponse: …` - `screenshot: str` A base64 encoded PNG image of the email. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) preview = client.email_security.investigate.preview.get( investigate_id="4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(preview.screenshot) ``` #### 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": { "screenshot": "screenshot" }, "success": true } ``` ## Preview for non-detection messages `email_security.investigate.preview.create(PreviewCreateParams**kwargs) -> PreviewCreateResponse` **post** `/accounts/{account_id}/email-security/investigate/preview` Generates a preview image for a message that was not flagged as a detection. Useful for investigating benign messages. Returns a base64-encoded PNG screenshot of the email body. ### Parameters - `account_id: str` Identifier. - `postfix_id: str` The identifier of the message ### Returns - `class PreviewCreateResponse: …` - `screenshot: str` A base64 encoded PNG image of the email. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) preview = client.email_security.investigate.preview.create( account_id="023e105f4ecef8ad9ca31a8372d0c353", postfix_id="4Njp3P0STMz2c02Q", ) print(preview.screenshot) ``` #### 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": { "screenshot": "screenshot" }, "success": true } ``` ## Domain Types ### Preview Get Response - `class PreviewGetResponse: …` - `screenshot: str` A base64 encoded PNG image of the email. ### Preview Create Response - `class PreviewCreateResponse: …` - `screenshot: str` A base64 encoded PNG image of the email. # Raw ## Get raw email content `email_security.investigate.raw.get(strinvestigate_id, RawGetParams**kwargs) -> RawGetResponse` **get** `/accounts/{account_id}/email-security/investigate/{investigate_id}/raw` Returns the raw eml of any non-benign message. ### Parameters - `account_id: str` Identifier. - `investigate_id: str` Unique identifier for a message retrieved from investigation ### Returns - `class RawGetResponse: …` - `raw: str` A UTF-8 encoded eml file of the email. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) raw = client.email_security.investigate.raw.get( investigate_id="4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(raw.raw) ``` #### 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": { "raw": "raw" }, "success": true } ``` ## Domain Types ### Raw Get Response - `class RawGetResponse: …` - `raw: str` A UTF-8 encoded eml file of the email. # Trace ## Get email trace `email_security.investigate.trace.get(strinvestigate_id, TraceGetParams**kwargs) -> TraceGetResponse` **get** `/accounts/{account_id}/email-security/investigate/{investigate_id}/trace` Retrieves delivery and processing trace information for an email message. Shows the delivery path, retraction history, and move operations performed on the message. Useful for debugging delivery issues. ### Parameters - `account_id: str` Identifier. - `investigate_id: str` Unique identifier for a message retrieved from investigation ### Returns - `class TraceGetResponse: …` - `inbound: Inbound` - `lines: Optional[List[InboundLine]]` - `lineno: Optional[int]` Line number in the trace log - `logged_at: Optional[datetime]` - `message: Optional[str]` - `ts: Optional[str]` Deprecated, use `logged_at` instead. End of life: November 1, 2026. - `pending: Optional[bool]` - `outbound: Outbound` - `lines: Optional[List[OutboundLine]]` - `lineno: Optional[int]` Line number in the trace log - `logged_at: Optional[datetime]` - `message: Optional[str]` - `ts: Optional[str]` Deprecated, use `logged_at` instead. End of life: November 1, 2026. - `pending: Optional[bool]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) trace = client.email_security.investigate.trace.get( investigate_id="4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(trace.inbound) ``` #### 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": { "inbound": { "lines": [ { "lineno": 0, "logged_at": "2019-12-27T18:11:19.117Z", "message": "message", "ts": "ts" } ], "pending": true }, "outbound": { "lines": [ { "lineno": 0, "logged_at": "2019-12-27T18:11:19.117Z", "message": "message", "ts": "ts" } ], "pending": true } }, "success": true } ``` ## Domain Types ### Trace Get Response - `class TraceGetResponse: …` - `inbound: Inbound` - `lines: Optional[List[InboundLine]]` - `lineno: Optional[int]` Line number in the trace log - `logged_at: Optional[datetime]` - `message: Optional[str]` - `ts: Optional[str]` Deprecated, use `logged_at` instead. End of life: November 1, 2026. - `pending: Optional[bool]` - `outbound: Outbound` - `lines: Optional[List[OutboundLine]]` - `lineno: Optional[int]` Line number in the trace log - `logged_at: Optional[datetime]` - `message: Optional[str]` - `ts: Optional[str]` Deprecated, use `logged_at` instead. End of life: November 1, 2026. - `pending: Optional[bool]` # Move ## Move a message `email_security.investigate.move.create(strinvestigate_id, MoveCreateParams**kwargs) -> SyncSinglePage[MoveCreateResponse]` **post** `/accounts/{account_id}/email-security/investigate/{investigate_id}/move` Moves a single message to a specified mailbox folder (Inbox, JunkEmail, DeletedItems, RecoverableItemsDeletions, or RecoverableItemsPurges). Requires active integration. ### Parameters - `account_id: str` Identifier. - `investigate_id: str` Unique identifier for a message retrieved from investigation - `destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]` - `"Inbox"` - `"JunkEmail"` - `"DeletedItems"` - `"RecoverableItemsDeletions"` - `"RecoverableItemsPurges"` ### Returns - `class MoveCreateResponse: …` - `success: bool` Whether the operation succeeded - `completed_at: Optional[datetime]` When the move operation completed (UTC) - `completed_timestamp: Optional[datetime]` Deprecated, use `completed_at` instead. End of life: November 1, 2026. - `destination: Optional[str]` Destination folder for the message - `item_count: Optional[int]` Number of items moved. End of life: November 1, 2026. - `message_id: Optional[str]` Message identifier - `operation: Optional[str]` Type of operation performed - `recipient: Optional[str]` Recipient email address - `status: Optional[str]` Operation status ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.investigate.move.create( investigate_id="4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678", account_id="023e105f4ecef8ad9ca31a8372d0c353", destination="Inbox", ) page = page.result[0] print(page.message_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": [ { "success": true, "completed_at": "2019-12-27T18:11:19.117Z", "completed_timestamp": "2019-12-27T18:11:19.117Z", "destination": "destination", "item_count": 0, "message_id": "message_id", "operation": "operation", "recipient": "recipient", "status": "status" } ], "success": true } ``` ## Move multiple messages `email_security.investigate.move.bulk(MoveBulkParams**kwargs) -> SyncSinglePage[MoveBulkResponse]` **post** `/accounts/{account_id}/email-security/investigate/move` Moves multiple messages to a specified mailbox folder (Inbox, JunkEmail, DeletedItems, RecoverableItemsDeletions, or RecoverableItemsPurges). Requires active integration. ### Parameters - `account_id: str` Identifier. - `destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]` - `"Inbox"` - `"JunkEmail"` - `"DeletedItems"` - `"RecoverableItemsDeletions"` - `"RecoverableItemsPurges"` - `ids: Optional[Sequence[str]]` List of message IDs to move - `postfix_ids: Optional[Sequence[str]]` Deprecated, use `ids` instead. End of life: November 1, 2026. List of message IDs to move. ### Returns - `class MoveBulkResponse: …` - `success: bool` Whether the operation succeeded - `completed_at: Optional[datetime]` When the move operation completed (UTC) - `completed_timestamp: Optional[datetime]` Deprecated, use `completed_at` instead. End of life: November 1, 2026. - `destination: Optional[str]` Destination folder for the message - `item_count: Optional[int]` Number of items moved. End of life: November 1, 2026. - `message_id: Optional[str]` Message identifier - `operation: Optional[str]` Type of operation performed - `recipient: Optional[str]` Recipient email address - `status: Optional[str]` Operation status ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.investigate.move.bulk( account_id="023e105f4ecef8ad9ca31a8372d0c353", destination="Inbox", ) page = page.result[0] print(page.message_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": [ { "success": true, "completed_at": "2019-12-27T18:11:19.117Z", "completed_timestamp": "2019-12-27T18:11:19.117Z", "destination": "destination", "item_count": 0, "message_id": "message_id", "operation": "operation", "recipient": "recipient", "status": "status" } ], "success": true } ``` ## Domain Types ### Move Create Response - `class MoveCreateResponse: …` - `success: bool` Whether the operation succeeded - `completed_at: Optional[datetime]` When the move operation completed (UTC) - `completed_timestamp: Optional[datetime]` Deprecated, use `completed_at` instead. End of life: November 1, 2026. - `destination: Optional[str]` Destination folder for the message - `item_count: Optional[int]` Number of items moved. End of life: November 1, 2026. - `message_id: Optional[str]` Message identifier - `operation: Optional[str]` Type of operation performed - `recipient: Optional[str]` Recipient email address - `status: Optional[str]` Operation status ### Move Bulk Response - `class MoveBulkResponse: …` - `success: bool` Whether the operation succeeded - `completed_at: Optional[datetime]` When the move operation completed (UTC) - `completed_timestamp: Optional[datetime]` Deprecated, use `completed_at` instead. End of life: November 1, 2026. - `destination: Optional[str]` Destination folder for the message - `item_count: Optional[int]` Number of items moved. End of life: November 1, 2026. - `message_id: Optional[str]` Message identifier - `operation: Optional[str]` Type of operation performed - `recipient: Optional[str]` Recipient email address - `status: Optional[str]` Operation status # Reclassify ## Change email classification `email_security.investigate.reclassify.create(strinvestigate_id, ReclassifyCreateParams**kwargs) -> object` **post** `/accounts/{account_id}/email-security/investigate/{investigate_id}/reclassify` Submits a request to reclassify an email's disposition. Use for reporting false positives or false negatives. Optionally provide the raw EML content for reanalysis. The reclassification is processed asynchronously. ### Parameters - `account_id: str` Identifier. - `investigate_id: str` Unique identifier for a message retrieved from investigation - `expected_disposition: Literal["NONE", "BULK", "MALICIOUS", 3 more]` - `"NONE"` - `"BULK"` - `"MALICIOUS"` - `"SPAM"` - `"SPOOF"` - `"SUSPICIOUS"` - `eml_content: Optional[str]` Base64 encoded content of the EML file. - `escalated_submission_id: Optional[str]` ### Returns - `object` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) reclassify = client.email_security.investigate.reclassify.create( investigate_id="4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678", account_id="023e105f4ecef8ad9ca31a8372d0c353", expected_disposition="NONE", ) print(reclassify) ``` #### 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": {}, "success": true } ``` # Release ## Release messages from quarantine `email_security.investigate.release.bulk(ReleaseBulkParams**kwargs) -> SyncSinglePage[ReleaseBulkResponse]` **post** `/accounts/{account_id}/email-security/investigate/release` Releases one or more quarantined messages, delivering them to the intended recipients. Use when a message was incorrectly quarantined. Returns delivery status for each recipient. ### Parameters - `account_id: str` Identifier. - `body: Sequence[str]` ### Returns - `class ReleaseBulkResponse: …` - `id: str` Unique identifier for a message retrieved from investigation - `delivered: Optional[List[str]]` - `failed: Optional[List[str]]` - `postfix_id: Optional[str]` Deprecated, use `id` instead. End of life: November 1, 2026. - `undelivered: Optional[List[str]]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.investigate.release.bulk( account_id="023e105f4ecef8ad9ca31a8372d0c353", body=["4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678"], ) 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-2024-01-05T10:00:00-12345678", "delivered": [ "string" ], "failed": [ "string" ], "postfix_id": "4Njp3P0STMz2c02Q", "undelivered": [ "string" ] } ], "success": true } ``` ## Domain Types ### Release Bulk Response - `class ReleaseBulkResponse: …` - `id: str` Unique identifier for a message retrieved from investigation - `delivered: Optional[List[str]]` - `failed: Optional[List[str]]` - `postfix_id: Optional[str]` Deprecated, use `id` instead. End of life: November 1, 2026. - `undelivered: Optional[List[str]]` # Phishguard # Reports ## Get PhishGuard reports `email_security.phishguard.reports.list(ReportListParams**kwargs) -> SyncSinglePage[ReportListResponse]` **get** `/accounts/{account_id}/email-security/phishguard/reports` Retrieves PhishGuard security alert reports for a specified date range. Reports include detected threats, dispositions, and contextual information. Use for security monitoring and threat analysis. ### Parameters - `account_id: str` Identifier. - `end: Optional[Union[str, datetime]]` End of the time range (RFC3339). Takes precedence over to_date. - `from_date: Optional[Union[null, null]]` Deprecated, use `start` instead. Start date in YYYY-MM-DD format. - `start: Optional[Union[str, datetime]]` Start of the time range (RFC3339). Takes precedence over from_date. - `to_date: Optional[Union[null, null]]` Deprecated, use `end` instead. End date in YYYY-MM-DD format. ### Returns - `class ReportListResponse: …` - `id: int` - `content: str` - `disposition: Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `fields: Fields` - `to: List[str]` - `from_: Optional[str]` - `occurred_at: Optional[datetime]` - `postfix_id: Optional[str]` - `ts: Optional[datetime]` Deprecated, use `occurred_at` instead - `priority: str` - `title: str` - `created_at: Optional[datetime]` - `tags: Optional[List[Tag]]` - `category: str` - `value: str` - `ts: Optional[datetime]` Deprecated, use `created_at` instead - `updated_at: Optional[datetime]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.phishguard.reports.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": 0, "content": "content", "disposition": "MALICIOUS", "fields": { "to": [ "string" ], "from": "from", "occurred_at": "2019-12-27T18:11:19.117Z", "postfix_id": "postfix_id", "ts": "2019-12-27T18:11:19.117Z" }, "priority": "priority", "title": "title", "created_at": "2019-12-27T18:11:19.117Z", "tags": [ { "category": "category", "value": "value" } ], "ts": "2019-12-27T18:11:19.117Z", "updated_at": "2019-12-27T18:11:19.117Z" } ], "success": true } ``` ## Domain Types ### Report List Response - `class ReportListResponse: …` - `id: int` - `content: str` - `disposition: Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `fields: Fields` - `to: List[str]` - `from_: Optional[str]` - `occurred_at: Optional[datetime]` - `postfix_id: Optional[str]` - `ts: Optional[datetime]` Deprecated, use `occurred_at` instead - `priority: str` - `title: str` - `created_at: Optional[datetime]` - `tags: Optional[List[Tag]]` - `category: str` - `value: str` - `ts: Optional[datetime]` Deprecated, use `created_at` instead - `updated_at: Optional[datetime]` # Settings # Allow Policies ## List email allow policies `email_security.settings.allow_policies.list(AllowPolicyListParams**kwargs) -> SyncV4PagePaginationArray[AllowPolicyListResponse]` **get** `/accounts/{account_id}/email-security/settings/allow_policies` Returns a paginated list of email allow policies. These policies exempt matching emails from security detection, allowing them to bypass disposition actions. Supports filtering by pattern type and policy attributes. ### Parameters - `account_id: str` Identifier. - `direction: Optional[Literal["asc", "desc"]]` The sorting direction. - `"asc"` - `"desc"` - `is_acceptable_sender: Optional[bool]` Filter to show only policies where messages from the sender are exempted from Spam, Spoof, and Bulk dispositions (not Malicious or Suspicious). - `is_exempt_recipient: Optional[bool]` Filter to show only policies where messages to the recipient bypass all detections. - `is_trusted_sender: Optional[bool]` Filter to show only policies where messages from the sender bypass all detections and link following. - `order: Optional[Literal["pattern", "created_at"]]` Field to sort by. - `"pattern"` - `"created_at"` - `page: Optional[int]` Current page within paginated list of results. - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `per_page: Optional[int]` The number of results per page. Maximum value is 1000. - `search: Optional[str]` Search term for filtering records. Behavior may change. - `verify_sender: Optional[bool]` Filter to show only policies that enforce DMARC, SPF, or DKIM authentication. ### Returns - `class AllowPolicyListResponse: …` An email allow policy - `id: str` Allow policy identifier - `created_at: datetime` - `last_modified: datetime` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `comments: Optional[str]` - `is_acceptable_sender: Optional[bool]` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: Optional[bool]` Messages to this recipient will bypass all detections - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_regex: Optional[bool]` - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. - `is_trusted_sender: Optional[bool]` Messages from this sender will bypass all detections and link following - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: Optional[bool]` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.settings.allow_policies.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" } } ], "success": true, "result": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "created_at": "2014-01-01T05:20:00.12345Z", "last_modified": "2014-01-01T05:20:00.12345Z", "comments": "Trust all messages send from test@example.com", "is_acceptable_sender": false, "is_exempt_recipient": false, "is_recipient": false, "is_regex": false, "is_sender": true, "is_spoof": false, "is_trusted_sender": true, "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "test@example.com", "pattern_type": "EMAIL", "verify_sender": true } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Get an email allow policy `email_security.settings.allow_policies.get(strpolicy_id, AllowPolicyGetParams**kwargs) -> AllowPolicyGetResponse` **get** `/accounts/{account_id}/email-security/settings/allow_policies/{policy_id}` Retrieves details for a specific allow policy including its pattern, dispositions that are exempted, and whether it applies to all detections. ### Parameters - `account_id: str` Identifier. - `policy_id: str` Allow policy identifier ### Returns - `class AllowPolicyGetResponse: …` An email allow policy - `id: str` Allow policy identifier - `created_at: datetime` - `last_modified: datetime` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `comments: Optional[str]` - `is_acceptable_sender: Optional[bool]` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: Optional[bool]` Messages to this recipient will bypass all detections - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_regex: Optional[bool]` - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. - `is_trusted_sender: Optional[bool]` Messages from this sender will bypass all detections and link following - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: Optional[bool]` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) allow_policy = client.email_security.settings.allow_policies.get( policy_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(allow_policy.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "created_at": "2014-01-01T05:20:00.12345Z", "last_modified": "2014-01-01T05:20:00.12345Z", "comments": "Trust all messages send from test@example.com", "is_acceptable_sender": false, "is_exempt_recipient": false, "is_recipient": false, "is_regex": false, "is_sender": true, "is_spoof": false, "is_trusted_sender": true, "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "test@example.com", "pattern_type": "EMAIL", "verify_sender": true } } ``` ## Create email allow policy `email_security.settings.allow_policies.create(AllowPolicyCreateParams**kwargs) -> AllowPolicyCreateResponse` **post** `/accounts/{account_id}/email-security/settings/allow_policies` Creates a new allow policy that exempts matching emails from security detections. Use with caution as this bypasses email security scanning. Policies can match on sender patterns and apply to specific detections or all detections. ### Parameters - `account_id: str` Identifier. - `is_acceptable_sender: bool` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: bool` Messages to this recipient will bypass all detections - `is_regex: bool` - `is_trusted_sender: bool` Messages from this sender will bypass all detections and link following - `pattern: str` - `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: bool` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. - `comments: Optional[str]` - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. ### Returns - `class AllowPolicyCreateResponse: …` An email allow policy - `id: str` Allow policy identifier - `created_at: datetime` - `last_modified: datetime` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `comments: Optional[str]` - `is_acceptable_sender: Optional[bool]` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: Optional[bool]` Messages to this recipient will bypass all detections - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_regex: Optional[bool]` - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. - `is_trusted_sender: Optional[bool]` Messages from this sender will bypass all detections and link following - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: Optional[bool]` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) allow_policy = client.email_security.settings.allow_policies.create( account_id="023e105f4ecef8ad9ca31a8372d0c353", is_acceptable_sender=False, is_exempt_recipient=False, is_regex=False, is_trusted_sender=True, pattern="test@example.com", pattern_type="EMAIL", verify_sender=True, ) print(allow_policy.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "created_at": "2014-01-01T05:20:00.12345Z", "last_modified": "2014-01-01T05:20:00.12345Z", "comments": "Trust all messages send from test@example.com", "is_acceptable_sender": false, "is_exempt_recipient": false, "is_recipient": false, "is_regex": false, "is_sender": true, "is_spoof": false, "is_trusted_sender": true, "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "test@example.com", "pattern_type": "EMAIL", "verify_sender": true } } ``` ## Update an email allow policy `email_security.settings.allow_policies.edit(strpolicy_id, AllowPolicyEditParams**kwargs) -> AllowPolicyEditResponse` **patch** `/accounts/{account_id}/email-security/settings/allow_policies/{policy_id}` Updates an existing allow policy. Only provided fields will be modified. Changes take effect for new emails matching the pattern. ### Parameters - `account_id: str` Identifier. - `policy_id: str` Allow policy identifier - `comments: Optional[str]` - `is_acceptable_sender: Optional[bool]` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: Optional[bool]` Messages to this recipient will bypass all detections - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_regex: Optional[bool]` - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. - `is_trusted_sender: Optional[bool]` Messages from this sender will bypass all detections and link following - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: Optional[bool]` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. ### Returns - `class AllowPolicyEditResponse: …` An email allow policy - `id: str` Allow policy identifier - `created_at: datetime` - `last_modified: datetime` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `comments: Optional[str]` - `is_acceptable_sender: Optional[bool]` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: Optional[bool]` Messages to this recipient will bypass all detections - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_regex: Optional[bool]` - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. - `is_trusted_sender: Optional[bool]` Messages from this sender will bypass all detections and link following - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: Optional[bool]` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.email_security.settings.allow_policies.edit( policy_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(response.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "created_at": "2014-01-01T05:20:00.12345Z", "last_modified": "2014-01-01T05:20:00.12345Z", "comments": "Trust all messages send from test@example.com", "is_acceptable_sender": false, "is_exempt_recipient": false, "is_recipient": false, "is_regex": false, "is_sender": true, "is_spoof": false, "is_trusted_sender": true, "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "test@example.com", "pattern_type": "EMAIL", "verify_sender": true } } ``` ## Delete an email allow policy `email_security.settings.allow_policies.delete(strpolicy_id, AllowPolicyDeleteParams**kwargs) -> AllowPolicyDeleteResponse` **delete** `/accounts/{account_id}/email-security/settings/allow_policies/{policy_id}` Removes an allow policy. After deletion, emails matching this pattern will be subject to normal security scanning and disposition actions. ### Parameters - `account_id: str` Identifier. - `policy_id: str` Allow policy identifier ### Returns - `class AllowPolicyDeleteResponse: …` - `id: str` Allow policy identifier ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) allow_policy = client.email_security.settings.allow_policies.delete( policy_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(allow_policy.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } } ``` ## Domain Types ### Allow Policy List Response - `class AllowPolicyListResponse: …` An email allow policy - `id: str` Allow policy identifier - `created_at: datetime` - `last_modified: datetime` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `comments: Optional[str]` - `is_acceptable_sender: Optional[bool]` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: Optional[bool]` Messages to this recipient will bypass all detections - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_regex: Optional[bool]` - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. - `is_trusted_sender: Optional[bool]` Messages from this sender will bypass all detections and link following - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: Optional[bool]` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. ### Allow Policy Get Response - `class AllowPolicyGetResponse: …` An email allow policy - `id: str` Allow policy identifier - `created_at: datetime` - `last_modified: datetime` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `comments: Optional[str]` - `is_acceptable_sender: Optional[bool]` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: Optional[bool]` Messages to this recipient will bypass all detections - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_regex: Optional[bool]` - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. - `is_trusted_sender: Optional[bool]` Messages from this sender will bypass all detections and link following - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: Optional[bool]` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. ### Allow Policy Create Response - `class AllowPolicyCreateResponse: …` An email allow policy - `id: str` Allow policy identifier - `created_at: datetime` - `last_modified: datetime` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `comments: Optional[str]` - `is_acceptable_sender: Optional[bool]` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: Optional[bool]` Messages to this recipient will bypass all detections - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_regex: Optional[bool]` - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. - `is_trusted_sender: Optional[bool]` Messages from this sender will bypass all detections and link following - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: Optional[bool]` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. ### Allow Policy Edit Response - `class AllowPolicyEditResponse: …` An email allow policy - `id: str` Allow policy identifier - `created_at: datetime` - `last_modified: datetime` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `comments: Optional[str]` - `is_acceptable_sender: Optional[bool]` Messages from this sender will be exempted from Spam, Spoof and Bulk dispositions. Note - This will not exempt messages with Malicious or Suspicious dispositions. - `is_exempt_recipient: Optional[bool]` Messages to this recipient will bypass all detections - `is_recipient: Optional[bool]` Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026. - `is_regex: Optional[bool]` - `is_sender: Optional[bool]` Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026. - `is_spoof: Optional[bool]` Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026. - `is_trusted_sender: Optional[bool]` Messages from this sender will bypass all detections and link following - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `verify_sender: Optional[bool]` Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication. ### Allow Policy Delete Response - `class AllowPolicyDeleteResponse: …` - `id: str` Allow policy identifier # Block Senders ## List blocked email senders `email_security.settings.block_senders.list(BlockSenderListParams**kwargs) -> SyncV4PagePaginationArray[BlockSenderListResponse]` **get** `/accounts/{account_id}/email-security/settings/block_senders` Returns a paginated list of blocked email sender patterns. These patterns prevent emails from matching senders from being delivered. Supports filtering by pattern type and searching across patterns. ### Parameters - `account_id: str` Identifier. - `direction: Optional[Literal["asc", "desc"]]` The sorting direction. - `"asc"` - `"desc"` - `order: Optional[Literal["pattern", "created_at"]]` Field to sort by. - `"pattern"` - `"created_at"` - `page: Optional[int]` Current page within paginated list of results. - `pattern: Optional[str]` Filter by pattern value. - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Filter by pattern type. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `per_page: Optional[int]` The number of results per page. Maximum value is 1000. - `search: Optional[str]` Search term for filtering records. Behavior may change. ### Returns - `class BlockSenderListResponse: …` A blocked sender pattern - `id: Optional[str]` Blocked sender pattern identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.settings.block_senders.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" } } ], "success": true, "result": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "Block sender with email test@example.com", "created_at": "2014-01-01T05:20:00.12345Z", "is_regex": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "test@example.com", "pattern_type": "EMAIL" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Get a blocked email sender `email_security.settings.block_senders.get(strpattern_id, BlockSenderGetParams**kwargs) -> BlockSenderGetResponse` **get** `/accounts/{account_id}/email-security/settings/block_senders/{pattern_id}` Retrieves details for a specific blocked sender pattern including its pattern type, value, and metadata. ### Parameters - `account_id: str` Identifier. - `pattern_id: str` Blocked sender pattern identifier ### Returns - `class BlockSenderGetResponse: …` A blocked sender pattern - `id: Optional[str]` Blocked sender pattern identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) block_sender = client.email_security.settings.block_senders.get( pattern_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(block_sender.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "Block sender with email test@example.com", "created_at": "2014-01-01T05:20:00.12345Z", "is_regex": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "test@example.com", "pattern_type": "EMAIL" } } ``` ## Create blocked email sender `email_security.settings.block_senders.create(BlockSenderCreateParams**kwargs) -> BlockSenderCreateResponse` **post** `/accounts/{account_id}/email-security/settings/block_senders` Creates a new blocked sender pattern. Emails matching this pattern will be blocked from delivery. Patterns can be email addresses, domains, or IP addresses, and support regular expressions. ### Parameters - `account_id: str` Identifier. - `is_regex: bool` - `pattern: str` - `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` - `comments: Optional[str]` ### Returns - `class BlockSenderCreateResponse: …` A blocked sender pattern - `id: Optional[str]` Blocked sender pattern identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) block_sender = client.email_security.settings.block_senders.create( account_id="023e105f4ecef8ad9ca31a8372d0c353", is_regex=False, pattern="test@example.com", pattern_type="EMAIL", ) print(block_sender.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "Block sender with email test@example.com", "created_at": "2014-01-01T05:20:00.12345Z", "is_regex": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "test@example.com", "pattern_type": "EMAIL" } } ``` ## Update a blocked email sender `email_security.settings.block_senders.edit(strpattern_id, BlockSenderEditParams**kwargs) -> BlockSenderEditResponse` **patch** `/accounts/{account_id}/email-security/settings/block_senders/{pattern_id}` Updates an existing blocked sender pattern. Only provided fields will be modified. The pattern will continue blocking emails until deleted. ### Parameters - `account_id: str` Identifier. - `pattern_id: str` Blocked sender pattern identifier - `comments: Optional[str]` - `is_regex: Optional[bool]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` ### Returns - `class BlockSenderEditResponse: …` A blocked sender pattern - `id: Optional[str]` Blocked sender pattern identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.email_security.settings.block_senders.edit( pattern_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(response.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "Block sender with email test@example.com", "created_at": "2014-01-01T05:20:00.12345Z", "is_regex": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "test@example.com", "pattern_type": "EMAIL" } } ``` ## Delete a blocked email sender `email_security.settings.block_senders.delete(strpattern_id, BlockSenderDeleteParams**kwargs) -> BlockSenderDeleteResponse` **delete** `/accounts/{account_id}/email-security/settings/block_senders/{pattern_id}` Removes a blocked sender pattern. After deletion, emails from this sender will no longer be automatically blocked based on this rule. ### Parameters - `account_id: str` Identifier. - `pattern_id: str` Blocked sender pattern identifier ### Returns - `class BlockSenderDeleteResponse: …` - `id: str` Blocked sender pattern identifier ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) block_sender = client.email_security.settings.block_senders.delete( pattern_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(block_sender.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } } ``` ## Domain Types ### Block Sender List Response - `class BlockSenderListResponse: …` A blocked sender pattern - `id: Optional[str]` Blocked sender pattern identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` ### Block Sender Get Response - `class BlockSenderGetResponse: …` A blocked sender pattern - `id: Optional[str]` Blocked sender pattern identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` ### Block Sender Create Response - `class BlockSenderCreateResponse: …` A blocked sender pattern - `id: Optional[str]` Blocked sender pattern identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` ### Block Sender Edit Response - `class BlockSenderEditResponse: …` A blocked sender pattern - `id: Optional[str]` Blocked sender pattern identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` - `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]` Type of pattern matching. Note: UNKNOWN is deprecated and cannot be used when creating or updating policies, but may be returned for existing entries. - `"EMAIL"` - `"DOMAIN"` - `"IP"` - `"UNKNOWN"` ### Block Sender Delete Response - `class BlockSenderDeleteResponse: …` - `id: str` Blocked sender pattern identifier # Domains ## List protected email domains `email_security.settings.domains.list(DomainListParams**kwargs) -> SyncV4PagePaginationArray[DomainListResponse]` **get** `/accounts/{account_id}/email-security/settings/domains` Returns a paginated list of email domains protected by Email Security. Includes domain configuration, delivery modes, and authorization status. Supports filtering by delivery mode and integration ID. ### Parameters - `account_id: str` Identifier. - `active_delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]` Currently active delivery mode to filter by. - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"API"` - `"RETRO_SCAN"` - `allowed_delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]` Delivery mode to filter by. - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"API"` - `"RETRO_SCAN"` - `direction: Optional[Literal["asc", "desc"]]` The sorting direction. - `"asc"` - `"desc"` - `domain: Optional[Sequence[str]]` Domain names to filter by. - `integration_id: Optional[str]` Integration ID to filter by. - `order: Optional[Literal["domain", "created_at"]]` Field to sort by. - `"domain"` - `"created_at"` - `page: Optional[int]` Current page within paginated list of results. - `per_page: Optional[int]` The number of results per page. Maximum value is 1000. - `search: Optional[str]` Search term for filtering records. Behavior may change. - `status: Optional[Literal["pending", "active", "failed", "timeout"]]` Filters response to domains with the provided status. - `"pending"` - `"active"` - `"failed"` - `"timeout"` ### Returns - `class DomainListResponse: …` - `id: Optional[str]` Domain identifier - `allowed_delivery_modes: Optional[List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]]` - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"API"` - `"RETRO_SCAN"` - `authorization: Optional[Authorization]` - `authorized: bool` - `timestamp: datetime` - `status_message: Optional[str]` - `created_at: Optional[datetime]` - `dmarc_status: Optional[Literal["none", "good", "invalid"]]` - `"none"` - `"good"` - `"invalid"` - `domain: Optional[str]` - `drop_dispositions: Optional[List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `emails_processed: Optional[EmailsProcessed]` - `timestamp: datetime` - `total_emails_processed: int` - `total_emails_processed_previous: int` - `folder: Optional[Literal["AllItems", "Inbox"]]` - `"AllItems"` - `"Inbox"` - `inbox_provider: Optional[Literal["Microsoft", "Google"]]` - `"Microsoft"` - `"Google"` - `integration_id: Optional[str]` - `ip_restrictions: Optional[List[str]]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `lookback_hops: Optional[int]` - `modified_at: Optional[datetime]` - `o365_tenant_id: Optional[str]` - `regions: Optional[List[Literal["GLOBAL", "AU", "DE", 2 more]]]` - `"GLOBAL"` - `"AU"` - `"DE"` - `"IN"` - `"US"` - `require_tls_inbound: Optional[bool]` - `require_tls_outbound: Optional[bool]` - `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]` - `"none"` - `"good"` - `"neutral"` - `"open"` - `"invalid"` - `status: Optional[Literal["pending", "active", "failed", "timeout"]]` - `"pending"` - `"active"` - `"failed"` - `"timeout"` - `transport: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.settings.domains.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" } } ], "success": true, "result": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "allowed_delivery_modes": [ "DIRECT" ], "authorization": { "authorized": true, "timestamp": "2019-12-27T18:11:19.117Z", "status_message": "status_message" }, "created_at": "2014-01-01T05:20:00.12345Z", "dmarc_status": "none", "domain": "example.com", "drop_dispositions": [ "MALICIOUS" ], "emails_processed": { "timestamp": "2019-12-27T18:11:19.117Z", "total_emails_processed": 0, "total_emails_processed_previous": 0 }, "folder": "AllItems", "inbox_provider": "Microsoft", "integration_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "ip_restrictions": [ "192.0.2.0/24", "2001:db8::/32" ], "last_modified": "2014-01-01T05:20:00.12345Z", "lookback_hops": 0, "modified_at": "2014-01-01T05:20:00.12345Z", "o365_tenant_id": "o365_tenant_id", "regions": [ "GLOBAL" ], "require_tls_inbound": true, "require_tls_outbound": true, "spf_status": "none", "status": "pending", "transport": "transport" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Get an email domain `email_security.settings.domains.get(strdomain_id, DomainGetParams**kwargs) -> DomainGetResponse` **get** `/accounts/{account_id}/email-security/settings/domains/{domain_id}` Retrieves detailed information for a specific protected email domain including its delivery configuration, SPF/DMARC status, and authorization state. ### Parameters - `account_id: str` Identifier. - `domain_id: str` Domain identifier ### Returns - `class DomainGetResponse: …` - `id: Optional[str]` Domain identifier - `allowed_delivery_modes: Optional[List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]]` - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"API"` - `"RETRO_SCAN"` - `authorization: Optional[Authorization]` - `authorized: bool` - `timestamp: datetime` - `status_message: Optional[str]` - `created_at: Optional[datetime]` - `dmarc_status: Optional[Literal["none", "good", "invalid"]]` - `"none"` - `"good"` - `"invalid"` - `domain: Optional[str]` - `drop_dispositions: Optional[List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `emails_processed: Optional[EmailsProcessed]` - `timestamp: datetime` - `total_emails_processed: int` - `total_emails_processed_previous: int` - `folder: Optional[Literal["AllItems", "Inbox"]]` - `"AllItems"` - `"Inbox"` - `inbox_provider: Optional[Literal["Microsoft", "Google"]]` - `"Microsoft"` - `"Google"` - `integration_id: Optional[str]` - `ip_restrictions: Optional[List[str]]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `lookback_hops: Optional[int]` - `modified_at: Optional[datetime]` - `o365_tenant_id: Optional[str]` - `regions: Optional[List[Literal["GLOBAL", "AU", "DE", 2 more]]]` - `"GLOBAL"` - `"AU"` - `"DE"` - `"IN"` - `"US"` - `require_tls_inbound: Optional[bool]` - `require_tls_outbound: Optional[bool]` - `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]` - `"none"` - `"good"` - `"neutral"` - `"open"` - `"invalid"` - `status: Optional[Literal["pending", "active", "failed", "timeout"]]` - `"pending"` - `"active"` - `"failed"` - `"timeout"` - `transport: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) domain = client.email_security.settings.domains.get( domain_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(domain.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "allowed_delivery_modes": [ "DIRECT" ], "authorization": { "authorized": true, "timestamp": "2019-12-27T18:11:19.117Z", "status_message": "status_message" }, "created_at": "2014-01-01T05:20:00.12345Z", "dmarc_status": "none", "domain": "example.com", "drop_dispositions": [ "MALICIOUS" ], "emails_processed": { "timestamp": "2019-12-27T18:11:19.117Z", "total_emails_processed": 0, "total_emails_processed_previous": 0 }, "folder": "AllItems", "inbox_provider": "Microsoft", "integration_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "ip_restrictions": [ "192.0.2.0/24", "2001:db8::/32" ], "last_modified": "2014-01-01T05:20:00.12345Z", "lookback_hops": 0, "modified_at": "2014-01-01T05:20:00.12345Z", "o365_tenant_id": "o365_tenant_id", "regions": [ "GLOBAL" ], "require_tls_inbound": true, "require_tls_outbound": true, "spf_status": "none", "status": "pending", "transport": "transport" } } ``` ## Update an email domain `email_security.settings.domains.edit(strdomain_id, DomainEditParams**kwargs) -> DomainEditResponse` **patch** `/accounts/{account_id}/email-security/settings/domains/{domain_id}` Updates configuration for a protected email domain. Only provided fields will be modified. Changes affect delivery mode, security settings, and regional processing. ### Parameters - `account_id: str` Identifier. - `domain_id: str` Domain identifier - `allowed_delivery_modes: Optional[List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]]` - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"API"` - `"RETRO_SCAN"` - `domain: Optional[str]` - `drop_dispositions: Optional[List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `folder: Optional[Literal["AllItems", "Inbox"]]` - `"AllItems"` - `"Inbox"` - `integration_id: Optional[str]` - `ip_restrictions: Optional[Sequence[str]]` - `lookback_hops: Optional[int]` - `regions: Optional[List[Literal["GLOBAL", "AU", "DE", 2 more]]]` - `"GLOBAL"` - `"AU"` - `"DE"` - `"IN"` - `"US"` - `require_tls_inbound: Optional[bool]` - `require_tls_outbound: Optional[bool]` - `transport: Optional[str]` ### Returns - `class DomainEditResponse: …` - `id: Optional[str]` Domain identifier - `allowed_delivery_modes: Optional[List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]]` - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"API"` - `"RETRO_SCAN"` - `authorization: Optional[Authorization]` - `authorized: bool` - `timestamp: datetime` - `status_message: Optional[str]` - `created_at: Optional[datetime]` - `dmarc_status: Optional[Literal["none", "good", "invalid"]]` - `"none"` - `"good"` - `"invalid"` - `domain: Optional[str]` - `drop_dispositions: Optional[List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `emails_processed: Optional[EmailsProcessed]` - `timestamp: datetime` - `total_emails_processed: int` - `total_emails_processed_previous: int` - `folder: Optional[Literal["AllItems", "Inbox"]]` - `"AllItems"` - `"Inbox"` - `inbox_provider: Optional[Literal["Microsoft", "Google"]]` - `"Microsoft"` - `"Google"` - `integration_id: Optional[str]` - `ip_restrictions: Optional[List[str]]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `lookback_hops: Optional[int]` - `modified_at: Optional[datetime]` - `o365_tenant_id: Optional[str]` - `regions: Optional[List[Literal["GLOBAL", "AU", "DE", 2 more]]]` - `"GLOBAL"` - `"AU"` - `"DE"` - `"IN"` - `"US"` - `require_tls_inbound: Optional[bool]` - `require_tls_outbound: Optional[bool]` - `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]` - `"none"` - `"good"` - `"neutral"` - `"open"` - `"invalid"` - `status: Optional[Literal["pending", "active", "failed", "timeout"]]` - `"pending"` - `"active"` - `"failed"` - `"timeout"` - `transport: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.email_security.settings.domains.edit( domain_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(response.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "allowed_delivery_modes": [ "DIRECT" ], "authorization": { "authorized": true, "timestamp": "2019-12-27T18:11:19.117Z", "status_message": "status_message" }, "created_at": "2014-01-01T05:20:00.12345Z", "dmarc_status": "none", "domain": "example.com", "drop_dispositions": [ "MALICIOUS" ], "emails_processed": { "timestamp": "2019-12-27T18:11:19.117Z", "total_emails_processed": 0, "total_emails_processed_previous": 0 }, "folder": "AllItems", "inbox_provider": "Microsoft", "integration_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "ip_restrictions": [ "192.0.2.0/24", "2001:db8::/32" ], "last_modified": "2014-01-01T05:20:00.12345Z", "lookback_hops": 0, "modified_at": "2014-01-01T05:20:00.12345Z", "o365_tenant_id": "o365_tenant_id", "regions": [ "GLOBAL" ], "require_tls_inbound": true, "require_tls_outbound": true, "spf_status": "none", "status": "pending", "transport": "transport" } } ``` ## Unprotect an email domain `email_security.settings.domains.delete(strdomain_id, DomainDeleteParams**kwargs) -> DomainDeleteResponse` **delete** `/accounts/{account_id}/email-security/settings/domains/{domain_id}` Removes email security protection from a domain. After deletion, emails for this domain will no longer be processed by Email Security. This action cannot be undone. ### Parameters - `account_id: str` Identifier. - `domain_id: str` Domain identifier ### Returns - `class DomainDeleteResponse: …` - `id: str` Domain identifier ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) domain = client.email_security.settings.domains.delete( domain_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(domain.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } } ``` ## Domain Types ### Domain List Response - `class DomainListResponse: …` - `id: Optional[str]` Domain identifier - `allowed_delivery_modes: Optional[List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]]` - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"API"` - `"RETRO_SCAN"` - `authorization: Optional[Authorization]` - `authorized: bool` - `timestamp: datetime` - `status_message: Optional[str]` - `created_at: Optional[datetime]` - `dmarc_status: Optional[Literal["none", "good", "invalid"]]` - `"none"` - `"good"` - `"invalid"` - `domain: Optional[str]` - `drop_dispositions: Optional[List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `emails_processed: Optional[EmailsProcessed]` - `timestamp: datetime` - `total_emails_processed: int` - `total_emails_processed_previous: int` - `folder: Optional[Literal["AllItems", "Inbox"]]` - `"AllItems"` - `"Inbox"` - `inbox_provider: Optional[Literal["Microsoft", "Google"]]` - `"Microsoft"` - `"Google"` - `integration_id: Optional[str]` - `ip_restrictions: Optional[List[str]]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `lookback_hops: Optional[int]` - `modified_at: Optional[datetime]` - `o365_tenant_id: Optional[str]` - `regions: Optional[List[Literal["GLOBAL", "AU", "DE", 2 more]]]` - `"GLOBAL"` - `"AU"` - `"DE"` - `"IN"` - `"US"` - `require_tls_inbound: Optional[bool]` - `require_tls_outbound: Optional[bool]` - `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]` - `"none"` - `"good"` - `"neutral"` - `"open"` - `"invalid"` - `status: Optional[Literal["pending", "active", "failed", "timeout"]]` - `"pending"` - `"active"` - `"failed"` - `"timeout"` - `transport: Optional[str]` ### Domain Get Response - `class DomainGetResponse: …` - `id: Optional[str]` Domain identifier - `allowed_delivery_modes: Optional[List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]]` - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"API"` - `"RETRO_SCAN"` - `authorization: Optional[Authorization]` - `authorized: bool` - `timestamp: datetime` - `status_message: Optional[str]` - `created_at: Optional[datetime]` - `dmarc_status: Optional[Literal["none", "good", "invalid"]]` - `"none"` - `"good"` - `"invalid"` - `domain: Optional[str]` - `drop_dispositions: Optional[List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `emails_processed: Optional[EmailsProcessed]` - `timestamp: datetime` - `total_emails_processed: int` - `total_emails_processed_previous: int` - `folder: Optional[Literal["AllItems", "Inbox"]]` - `"AllItems"` - `"Inbox"` - `inbox_provider: Optional[Literal["Microsoft", "Google"]]` - `"Microsoft"` - `"Google"` - `integration_id: Optional[str]` - `ip_restrictions: Optional[List[str]]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `lookback_hops: Optional[int]` - `modified_at: Optional[datetime]` - `o365_tenant_id: Optional[str]` - `regions: Optional[List[Literal["GLOBAL", "AU", "DE", 2 more]]]` - `"GLOBAL"` - `"AU"` - `"DE"` - `"IN"` - `"US"` - `require_tls_inbound: Optional[bool]` - `require_tls_outbound: Optional[bool]` - `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]` - `"none"` - `"good"` - `"neutral"` - `"open"` - `"invalid"` - `status: Optional[Literal["pending", "active", "failed", "timeout"]]` - `"pending"` - `"active"` - `"failed"` - `"timeout"` - `transport: Optional[str]` ### Domain Edit Response - `class DomainEditResponse: …` - `id: Optional[str]` Domain identifier - `allowed_delivery_modes: Optional[List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]]` - `"DIRECT"` - `"BCC"` - `"JOURNAL"` - `"API"` - `"RETRO_SCAN"` - `authorization: Optional[Authorization]` - `authorized: bool` - `timestamp: datetime` - `status_message: Optional[str]` - `created_at: Optional[datetime]` - `dmarc_status: Optional[Literal["none", "good", "invalid"]]` - `"none"` - `"good"` - `"invalid"` - `domain: Optional[str]` - `drop_dispositions: Optional[List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]]` - `"MALICIOUS"` - `"MALICIOUS-BEC"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"ENCRYPTED"` - `"EXTERNAL"` - `"UNKNOWN"` - `"NONE"` - `emails_processed: Optional[EmailsProcessed]` - `timestamp: datetime` - `total_emails_processed: int` - `total_emails_processed_previous: int` - `folder: Optional[Literal["AllItems", "Inbox"]]` - `"AllItems"` - `"Inbox"` - `inbox_provider: Optional[Literal["Microsoft", "Google"]]` - `"Microsoft"` - `"Google"` - `integration_id: Optional[str]` - `ip_restrictions: Optional[List[str]]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `lookback_hops: Optional[int]` - `modified_at: Optional[datetime]` - `o365_tenant_id: Optional[str]` - `regions: Optional[List[Literal["GLOBAL", "AU", "DE", 2 more]]]` - `"GLOBAL"` - `"AU"` - `"DE"` - `"IN"` - `"US"` - `require_tls_inbound: Optional[bool]` - `require_tls_outbound: Optional[bool]` - `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]` - `"none"` - `"good"` - `"neutral"` - `"open"` - `"invalid"` - `status: Optional[Literal["pending", "active", "failed", "timeout"]]` - `"pending"` - `"active"` - `"failed"` - `"timeout"` - `transport: Optional[str]` ### Domain Delete Response - `class DomainDeleteResponse: …` - `id: str` Domain identifier # Impersonation Registry ## List entries in impersonation registry `email_security.settings.impersonation_registry.list(ImpersonationRegistryListParams**kwargs) -> SyncV4PagePaginationArray[ImpersonationRegistryListResponse]` **get** `/accounts/{account_id}/email-security/settings/impersonation_registry` Returns a paginated list of protected identities in the impersonation registry. These entries define identities and email addresses to protect from impersonation attacks. Can be manually added or automatically synced from directory integrations. ### Parameters - `account_id: str` Identifier. - `direction: Optional[Literal["asc", "desc"]]` The sorting direction. - `"asc"` - `"desc"` - `order: Optional[Literal["name", "email", "created_at"]]` Field to sort by. - `"name"` - `"email"` - `"created_at"` - `page: Optional[int]` Current page within paginated list of results. - `per_page: Optional[int]` The number of results per page. Maximum value is 1000. - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` - `search: Optional[str]` Search term for filtering records. Behavior may change. ### Returns - `class ImpersonationRegistryListResponse: …` An impersonation registry entry - `id: Optional[str]` Impersonation registry entry identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `email: Optional[str]` - `external_directory_node_id: Optional[str]` - `is_email_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `name: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.settings.impersonation_registry.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" } } ], "success": true, "result": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "comments", "created_at": "2014-01-01T05:20:00.12345Z", "directory_id": 0, "directory_node_id": 0, "email": "john.doe@example.com", "external_directory_node_id": "external_directory_node_id", "is_email_regex": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "name": "John Doe", "provenance": "A1S_INTERNAL" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Get an impersonation registry entry `email_security.settings.impersonation_registry.get(strimpersonation_registry_id, ImpersonationRegistryGetParams**kwargs) -> ImpersonationRegistryGetResponse` **get** `/accounts/{account_id}/email-security/settings/impersonation_registry/{impersonation_registry_id}` Retrieves details for a specific impersonation registry entry including the protected identity, email pattern, and synchronization source if directory-synced. ### Parameters - `account_id: str` Identifier. - `impersonation_registry_id: str` Impersonation registry entry identifier ### Returns - `class ImpersonationRegistryGetResponse: …` An impersonation registry entry - `id: Optional[str]` Impersonation registry entry identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `email: Optional[str]` - `external_directory_node_id: Optional[str]` - `is_email_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `name: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) impersonation_registry = client.email_security.settings.impersonation_registry.get( impersonation_registry_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(impersonation_registry.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "comments", "created_at": "2014-01-01T05:20:00.12345Z", "directory_id": 0, "directory_node_id": 0, "email": "john.doe@example.com", "external_directory_node_id": "external_directory_node_id", "is_email_regex": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "name": "John Doe", "provenance": "A1S_INTERNAL" } } ``` ## Create impersonation registry entry `email_security.settings.impersonation_registry.create(ImpersonationRegistryCreateParams**kwargs) -> ImpersonationRegistryCreateResponse` **post** `/accounts/{account_id}/email-security/settings/impersonation_registry` Creates a new entry in the impersonation registry to protect against impersonation. Emails attempting to impersonate this identity will be flagged. Supports regex patterns for flexible email matching. ### Parameters - `account_id: str` Identifier. - `email: str` - `is_email_regex: bool` - `name: str` - `comments: Optional[str]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `external_directory_node_id: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Returns - `class ImpersonationRegistryCreateResponse: …` An impersonation registry entry - `id: Optional[str]` Impersonation registry entry identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `email: Optional[str]` - `external_directory_node_id: Optional[str]` - `is_email_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `name: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) impersonation_registry = client.email_security.settings.impersonation_registry.create( account_id="023e105f4ecef8ad9ca31a8372d0c353", email="john.doe@example.com", is_email_regex=False, name="John Doe", ) print(impersonation_registry.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "comments", "created_at": "2014-01-01T05:20:00.12345Z", "directory_id": 0, "directory_node_id": 0, "email": "john.doe@example.com", "external_directory_node_id": "external_directory_node_id", "is_email_regex": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "name": "John Doe", "provenance": "A1S_INTERNAL" } } ``` ## Update an impersonation registry entry `email_security.settings.impersonation_registry.edit(strimpersonation_registry_id, ImpersonationRegistryEditParams**kwargs) -> ImpersonationRegistryEditResponse` **patch** `/accounts/{account_id}/email-security/settings/impersonation_registry/{impersonation_registry_id}` Updates an existing impersonation registry entry. Only provided fields will be modified. Directory-synced entries can't be updated. ### Parameters - `account_id: str` Identifier. - `impersonation_registry_id: str` Impersonation registry entry identifier - `comments: Optional[str]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `email: Optional[str]` - `external_directory_node_id: Optional[str]` - `is_email_regex: Optional[bool]` - `name: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Returns - `class ImpersonationRegistryEditResponse: …` An impersonation registry entry - `id: Optional[str]` Impersonation registry entry identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `email: Optional[str]` - `external_directory_node_id: Optional[str]` - `is_email_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `name: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.email_security.settings.impersonation_registry.edit( impersonation_registry_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(response.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "comments", "created_at": "2014-01-01T05:20:00.12345Z", "directory_id": 0, "directory_node_id": 0, "email": "john.doe@example.com", "external_directory_node_id": "external_directory_node_id", "is_email_regex": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "name": "John Doe", "provenance": "A1S_INTERNAL" } } ``` ## Delete an impersonation registry entry `email_security.settings.impersonation_registry.delete(strimpersonation_registry_id, ImpersonationRegistryDeleteParams**kwargs) -> ImpersonationRegistryDeleteResponse` **delete** `/accounts/{account_id}/email-security/settings/impersonation_registry/{impersonation_registry_id}` Removes an entry from the impersonation registry. After deletion, this identity will no longer be protected from impersonation. ### Parameters - `account_id: str` Identifier. - `impersonation_registry_id: str` Impersonation registry entry identifier ### Returns - `class ImpersonationRegistryDeleteResponse: …` - `id: str` Impersonation registry entry identifier ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) impersonation_registry = client.email_security.settings.impersonation_registry.delete( impersonation_registry_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(impersonation_registry.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } } ``` ## Domain Types ### Impersonation Registry List Response - `class ImpersonationRegistryListResponse: …` An impersonation registry entry - `id: Optional[str]` Impersonation registry entry identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `email: Optional[str]` - `external_directory_node_id: Optional[str]` - `is_email_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `name: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Impersonation Registry Get Response - `class ImpersonationRegistryGetResponse: …` An impersonation registry entry - `id: Optional[str]` Impersonation registry entry identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `email: Optional[str]` - `external_directory_node_id: Optional[str]` - `is_email_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `name: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Impersonation Registry Create Response - `class ImpersonationRegistryCreateResponse: …` An impersonation registry entry - `id: Optional[str]` Impersonation registry entry identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `email: Optional[str]` - `external_directory_node_id: Optional[str]` - `is_email_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `name: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Impersonation Registry Edit Response - `class ImpersonationRegistryEditResponse: …` An impersonation registry entry - `id: Optional[str]` Impersonation registry entry identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `directory_id: Optional[int]` - `directory_node_id: Optional[int]` - `email: Optional[str]` - `external_directory_node_id: Optional[str]` - `is_email_regex: Optional[bool]` - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `name: Optional[str]` - `provenance: Optional[Literal["A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY"]]` - `"A1S_INTERNAL"` - `"SNOOPY-CASB_OFFICE_365"` - `"SNOOPY-OFFICE_365"` - `"SNOOPY-GOOGLE_DIRECTORY"` ### Impersonation Registry Delete Response - `class ImpersonationRegistryDeleteResponse: …` - `id: str` Impersonation registry entry identifier # Trusted Domains ## List trusted email domains `email_security.settings.trusted_domains.list(TrustedDomainListParams**kwargs) -> SyncV4PagePaginationArray[TrustedDomainListResponse]` **get** `/accounts/{account_id}/email-security/settings/trusted_domains` Returns a paginated list of trusted domain patterns. Trusted domains prevent false positives for recently registered domains and lookalike domain detections. Patterns can use regular expressions for flexible matching. ### Parameters - `account_id: str` Identifier. - `direction: Optional[Literal["asc", "desc"]]` The sorting direction. - `"asc"` - `"desc"` - `is_recent: Optional[bool]` Filter to show only recently registered domains that are trusted to prevent triggering Suspicious or Malicious dispositions. - `is_similarity: Optional[bool]` Filter to show only proximity domains (partner or approved domains with similar spelling to connected domains) that prevent Spoof dispositions. - `order: Optional[Literal["pattern", "created_at"]]` Field to sort by. - `"pattern"` - `"created_at"` - `page: Optional[int]` Current page within paginated list of results. - `pattern: Optional[str]` - `per_page: Optional[int]` The number of results per page. Maximum value is 1000. - `search: Optional[str]` Search term for filtering records. Behavior may change. ### Returns - `class TrustedDomainListResponse: …` A trusted email domain - `id: Optional[str]` Trusted domain identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_recent: Optional[bool]` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: Optional[bool]` - `is_similarity: Optional[bool]` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.settings.trusted_domains.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" } } ], "success": true, "result": [ { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "Trusted partner domain", "created_at": "2014-01-01T05:20:00.12345Z", "is_recent": true, "is_regex": false, "is_similarity": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "example.com" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Get a trusted email domain `email_security.settings.trusted_domains.get(strtrusted_domain_id, TrustedDomainGetParams**kwargs) -> TrustedDomainGetResponse` **get** `/accounts/{account_id}/email-security/settings/trusted_domains/{trusted_domain_id}` Retrieves details for a specific trusted domain pattern including its pattern value, whether it uses regex matching, and which detection types it affects. ### Parameters - `account_id: str` Identifier. - `trusted_domain_id: str` Trusted domain identifier ### Returns - `class TrustedDomainGetResponse: …` A trusted email domain - `id: Optional[str]` Trusted domain identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_recent: Optional[bool]` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: Optional[bool]` - `is_similarity: Optional[bool]` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) trusted_domain = client.email_security.settings.trusted_domains.get( trusted_domain_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(trusted_domain.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "Trusted partner domain", "created_at": "2014-01-01T05:20:00.12345Z", "is_recent": true, "is_regex": false, "is_similarity": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "example.com" } } ``` ## Create trusted email domain `email_security.settings.trusted_domains.create(TrustedDomainCreateParams**kwargs) -> TrustedDomainCreateResponse` **post** `/accounts/{account_id}/email-security/settings/trusted_domains` Creates a new trusted domain pattern. Use for partner domains or approved senders that should bypass recent domain registration and similarity checks. Configure whether it prevents recent domain or spoof dispositions. ### Parameters - `account_id: str` Identifier. - `is_recent: bool` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: bool` - `is_similarity: bool` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `pattern: str` - `comments: Optional[str]` ### Returns - `class TrustedDomainCreateResponse: …` A trusted email domain - `id: Optional[str]` Trusted domain identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_recent: Optional[bool]` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: Optional[bool]` - `is_similarity: Optional[bool]` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) trusted_domain = client.email_security.settings.trusted_domains.create( account_id="023e105f4ecef8ad9ca31a8372d0c353", is_recent=True, is_regex=False, is_similarity=False, pattern="example.com", ) print(trusted_domain.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "Trusted partner domain", "created_at": "2014-01-01T05:20:00.12345Z", "is_recent": true, "is_regex": false, "is_similarity": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "example.com" } } ``` ## Update a trusted email domain `email_security.settings.trusted_domains.edit(strtrusted_domain_id, TrustedDomainEditParams**kwargs) -> TrustedDomainEditResponse` **patch** `/accounts/{account_id}/email-security/settings/trusted_domains/{trusted_domain_id}` Updates an existing trusted domain pattern. Only provided fields will be modified. Changes take effect for new emails matching the pattern. ### Parameters - `account_id: str` Identifier. - `trusted_domain_id: str` Trusted domain identifier - `comments: Optional[str]` - `is_recent: Optional[bool]` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: Optional[bool]` - `is_similarity: Optional[bool]` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `pattern: Optional[str]` ### Returns - `class TrustedDomainEditResponse: …` A trusted email domain - `id: Optional[str]` Trusted domain identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_recent: Optional[bool]` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: Optional[bool]` - `is_similarity: Optional[bool]` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.email_security.settings.trusted_domains.edit( trusted_domain_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(response.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "comments": "Trusted partner domain", "created_at": "2014-01-01T05:20:00.12345Z", "is_recent": true, "is_regex": false, "is_similarity": false, "last_modified": "2014-01-01T05:20:00.12345Z", "modified_at": "2014-01-01T05:20:00.12345Z", "pattern": "example.com" } } ``` ## Delete a trusted email domain `email_security.settings.trusted_domains.delete(strtrusted_domain_id, TrustedDomainDeleteParams**kwargs) -> TrustedDomainDeleteResponse` **delete** `/accounts/{account_id}/email-security/settings/trusted_domains/{trusted_domain_id}` Removes a trusted domain pattern. After deletion, emails from this domain will be subject to normal recent domain and similarity checks. ### Parameters - `account_id: str` Identifier. - `trusted_domain_id: str` Trusted domain identifier ### Returns - `class TrustedDomainDeleteResponse: …` - `id: str` Trusted domain identifier ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) trusted_domain = client.email_security.settings.trusted_domains.delete( trusted_domain_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(trusted_domain.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" } } ], "success": true, "result": { "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } } ``` ## Domain Types ### Trusted Domain List Response - `class TrustedDomainListResponse: …` A trusted email domain - `id: Optional[str]` Trusted domain identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_recent: Optional[bool]` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: Optional[bool]` - `is_similarity: Optional[bool]` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` ### Trusted Domain Get Response - `class TrustedDomainGetResponse: …` A trusted email domain - `id: Optional[str]` Trusted domain identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_recent: Optional[bool]` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: Optional[bool]` - `is_similarity: Optional[bool]` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` ### Trusted Domain Create Response - `class TrustedDomainCreateResponse: …` A trusted email domain - `id: Optional[str]` Trusted domain identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_recent: Optional[bool]` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: Optional[bool]` - `is_similarity: Optional[bool]` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` ### Trusted Domain Edit Response - `class TrustedDomainEditResponse: …` A trusted email domain - `id: Optional[str]` Trusted domain identifier - `comments: Optional[str]` - `created_at: Optional[datetime]` - `is_recent: Optional[bool]` Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition. - `is_regex: Optional[bool]` - `is_similarity: Optional[bool]` Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition. - `last_modified: Optional[datetime]` Deprecated, use `modified_at` instead. End of life: November 1, 2026. - `modified_at: Optional[datetime]` - `pattern: Optional[str]` ### Trusted Domain Delete Response - `class TrustedDomainDeleteResponse: …` - `id: str` Trusted domain identifier # Submissions ## Get reclassify submissions `email_security.submissions.list(SubmissionListParams**kwargs) -> SyncV4PagePaginationArray[SubmissionListResponse]` **get** `/accounts/{account_id}/email-security/submissions` Returns information for submissions made to reclassify emails. Shows the status, outcome, and disposition changes for reclassification requests made by users or the security team. Useful for tracking false positive/negative reports. ### Parameters - `account_id: str` Identifier. - `end: Optional[Union[str, datetime]]` The end of the search date range. Defaults to `now`. - `escalated_from_user: Optional[bool]` When true, return only submissions that were escalated by an end user (vs. by the security team). When false, return only submissions that were not escalated by an end user. When omitted, no filter is applied. - `original_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `outcome_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `page: Optional[int]` Current page within paginated list of results. - `per_page: Optional[int]` The number of results per page. Maximum value is 1000. - `query: Optional[str]` - `requested_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `start: Optional[Union[str, datetime]]` The beginning of the search date range. Defaults to `now - 30 days`. - `status: Optional[str]` - `submission_id: Optional[str]` - `type: Optional[Literal["TEAM", "USER"]]` - `"TEAM"` - `"USER"` ### Returns - `class SubmissionListResponse: …` - `requested_at: datetime` When the submission was requested (UTC). - `submission_id: str` - `customer_status: Optional[Literal["escalated", "reviewed", "unreviewed"]]` - `"escalated"` - `"reviewed"` - `"unreviewed"` - `escalated_as: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `escalated_at: Optional[datetime]` - `escalated_by: Optional[str]` - `escalated_submission_id: Optional[str]` - `original_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `original_edf_hash: Optional[str]` - `original_postfix_id: Optional[str]` The postfix ID of the original message that was submitted - `outcome: Optional[str]` - `outcome_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `requested_by: Optional[str]` - `requested_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `requested_ts: Optional[str]` Deprecated, use `requested_at` instead - `status: Optional[str]` - `subject: Optional[str]` - `type: Optional[Literal["Team", "User"]]` Whether the submission was created by a team member or an end user. - `"Team"` - `"User"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) page = client.email_security.submissions.list( account_id="023e105f4ecef8ad9ca31a8372d0c353", ) page = page.result[0] print(page.submission_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" } } ], "success": true, "result": [ { "requested_at": "2019-12-27T18:11:19.117Z", "submission_id": "submission_id", "customer_status": "escalated", "escalated_as": "MALICIOUS", "escalated_at": "2019-12-27T18:11:19.117Z", "escalated_by": "escalated_by", "escalated_submission_id": "escalated_submission_id", "original_disposition": "MALICIOUS", "original_edf_hash": "original_edf_hash", "original_postfix_id": "original_postfix_id", "outcome": "outcome", "outcome_disposition": "MALICIOUS", "requested_by": "requested_by", "requested_disposition": "MALICIOUS", "requested_ts": "requested_ts", "status": "status", "subject": "subject", "type": "Team" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Domain Types ### Submission List Response - `class SubmissionListResponse: …` - `requested_at: datetime` When the submission was requested (UTC). - `submission_id: str` - `customer_status: Optional[Literal["escalated", "reviewed", "unreviewed"]]` - `"escalated"` - `"reviewed"` - `"unreviewed"` - `escalated_as: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `escalated_at: Optional[datetime]` - `escalated_by: Optional[str]` - `escalated_submission_id: Optional[str]` - `original_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `original_edf_hash: Optional[str]` - `original_postfix_id: Optional[str]` The postfix ID of the original message that was submitted - `outcome: Optional[str]` - `outcome_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `requested_by: Optional[str]` - `requested_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]` - `"MALICIOUS"` - `"SUSPICIOUS"` - `"SPOOF"` - `"SPAM"` - `"BULK"` - `"NONE"` - `requested_ts: Optional[str]` Deprecated, use `requested_at` instead - `status: Optional[str]` - `subject: Optional[str]` - `type: Optional[Literal["Team", "User"]]` Whether the submission was created by a team member or an end user. - `"Team"` - `"User"`