# 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).
If the search takes too long, the endpoint returns 202 with a Location header
pointing to a polling endpoint where results can be retrieved once ready.
### Parameters
- `account_id: str`
Account Identifier
- `action_log: Optional[bool]`
Determines if the message action log is included in the response.
- `alert_id: Optional[str]`
- `cursor: Optional[str]`
- `detections_only: Optional[bool]`
Determines if the search results will include detections or not.
- `domain: Optional[str]`
Filter by a domain found in the email: sender domain, recipient domain, or a domain in a link.
- `end: Optional[Union[str, datetime]]`
The end of the search date range.
Defaults to `now` if not provided.
- `exact_subject: Optional[str]`
Search for messages with an exact subject match.
- `final_disposition: Optional[Literal["MALICIOUS", "SUSPICIOUS", "SPOOF", 3 more]]`
The dispositions the search filters by.
- `"MALICIOUS"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"NONE"`
- `message_action: Optional[Literal["PREVIEW", "QUARANTINE_RELEASED", "MOVED", "SUBMITTED"]]`
The message actions the search filters by.
- `"PREVIEW"`
- `"QUARANTINE_RELEASED"`
- `"MOVED"`
- `"SUBMITTED"`
- `message_id: Optional[str]`
- `metric: Optional[str]`
- `page: Optional[int]`
Deprecated: Use cursor pagination instead.
- `per_page: Optional[int]`
The number of results per page.
- `query: Optional[str]`
The space-delimited term used in the query. The search is case-insensitive.
The content of the following email metadata fields are searched:
* alert_id
* CC
* From (envelope_from)
* From Name
* final_disposition
* md5 hash (of any attachment)
* sha1 hash (of any attachment)
* sha256 hash (of any attachment)
* name (of any attachment)
* Reason
* Received DateTime (yyyy-mm-ddThh:mm:ss)
* Sent DateTime (yyyy-mm-ddThh:mm:ss)
* ReplyTo
* To (envelope_to)
* To Name
* Message-ID
* smtp_helo_server_ip
* smtp_previous_hop_ip
* x_originating_ip
* Subject
- `recipient: Optional[str]`
Filter by recipient. Matches either an email address or a domain.
- `sender: Optional[str]`
Filter by sender. Matches either an email address or a domain.
- `start: Optional[Union[str, datetime]]`
The beginning of the search date range.
Defaults to `now - 30 days` if not provided.
- `subject: Optional[str]`
Search for messages containing individual keywords in any order within the subject.
- `submissions: Optional[bool]`
Search for submissions instead of original messages
### Returns
- `class InvestigateListResponse: …`
- `id: str`
- `action_log: object`
- `client_recipients: List[str]`
- `detection_reasons: List[str]`
- `is_phish_submission: bool`
- `is_quarantined: bool`
- `postfix_id: str`
The identifier of the message.
- `properties: Properties`
- `allowlisted_pattern: Optional[str]`
- `allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `blocklisted_message: Optional[bool]`
- `blocklisted_pattern: Optional[str]`
- `whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `ts: str`
Deprecated, use `scanned_at` instead
- `alert_id: Optional[str]`
- `delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 8 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"REVIEW_SUBMISSION"`
- `"DMARC_UNVERIFIED"`
- `"DMARC_FAILURE_REPORT"`
- `"DMARC_AGGREGATE_REPORT"`
- `"THREAT_INTEL_SUBMISSION"`
- `"SIMULATION_SUBMISSION"`
- `"API"`
- `"RETRO_SCAN"`
- `edf_hash: Optional[str]`
- `envelope_from: Optional[str]`
- `envelope_to: Optional[List[str]]`
- `final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `findings: Optional[List[Finding]]`
- `attachment: Optional[str]`
- `detail: Optional[str]`
- `detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `field: Optional[str]`
- `name: Optional[str]`
- `portion: Optional[str]`
- `reason: Optional[str]`
- `score: Optional[float]`
- `value: Optional[str]`
- `from_: Optional[str]`
- `from_name: Optional[str]`
- `htmltext_structure_hash: Optional[str]`
- `message_id: Optional[str]`
- `post_delivery_operations: Optional[List[Literal["PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE"]]]`
- `"PREVIEW"`
- `"QUARANTINE_RELEASE"`
- `"SUBMISSION"`
- `"MOVE"`
- `postfix_id_outbound: Optional[str]`
- `replyto: Optional[str]`
- `scanned_at: Optional[datetime]`
- `sent_at: Optional[datetime]`
- `sent_date: Optional[str]`
Deprecated, use `sent_at` instead
- `subject: Optional[str]`
- `threat_categories: Optional[List[str]]`
- `to: Optional[List[str]]`
- `to_name: Optional[List[str]]`
- `validation: Optional[Validation]`
- `comment: Optional[str]`
- `dkim: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.investigate.list(
account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
page = page.result[0]
print(page.id)
```
#### Response
```json
{
"errors": [
{
"code": 1000,
"message": "message",
"documentation_url": "documentation_url",
"source": {
"pointer": "pointer"
}
}
],
"messages": [
{
"code": 1000,
"message": "message",
"documentation_url": "documentation_url",
"source": {
"pointer": "pointer"
}
}
],
"result": [
{
"id": "4Njp3P0STMz2c02Q-2022-12-30T02:44:49-2a539d65",
"action_log": [],
"client_recipients": [
"email@example.com"
],
"detection_reasons": [
"Selector is a source of spam/uce : Smtp-Helo-Server-Ip=127.0.0[dot]186"
],
"is_phish_submission": false,
"is_quarantined": false,
"postfix_id": "47JJcT1w6GztQV7",
"properties": {
"allowlisted_pattern": "allowlisted_pattern",
"allowlisted_pattern_type": "quarantine_release",
"blocklisted_message": true,
"blocklisted_pattern": "blocklisted_pattern",
"whitelisted_pattern_type": "quarantine_release"
},
"ts": "2019-11-20T23:22:01",
"alert_id": "4Njp3P0STMz2c02Q-2022-12-30T02:44:49",
"delivery_mode": "DIRECT",
"edf_hash": null,
"envelope_from": "d1994@example.com",
"envelope_to": [
"email@example.com"
],
"final_disposition": "MALICIOUS",
"findings": [
{
"attachment": "attachment",
"detail": "detail",
"detection": "MALICIOUS",
"field": "field",
"name": "name",
"portion": "portion",
"reason": "reason",
"score": 0,
"value": "value"
}
],
"from": "d1994@example.com",
"from_name": "Sender Name",
"htmltext_structure_hash": null,
"message_id": "<4VAZPrAdg7IGNxdt1DWRNu0gvOeL_iZiwP4BQfo4DaE.Yw-woXuugQbeFhBpzwFQtqq_v2v1HOKznoMBqbciQpE@example.com>",
"post_delivery_operations": [
"PREVIEW"
],
"postfix_id_outbound": null,
"replyto": "email@example.com",
"scanned_at": "2019-11-20T23:22:01Z",
"sent_at": "2019-11-21T00:22:01Z",
"sent_date": "2019-11-21T00:22:01",
"subject": "listen, I highly recommend u to read that email, just to ensure not a thing will take place",
"threat_categories": [
"IPReputation",
"ASNReputation"
],
"to": [
"email@example.com"
],
"to_name": [
"Recipient Name"
],
"validation": {
"comment": null,
"dkim": "pass",
"dmarc": "none",
"spf": "fail"
}
}
],
"result_info": {
"count": 0,
"page": 0,
"per_page": 0,
"total_count": 0,
"next": "next",
"previous": "previous"
},
"success": true
}
```
## Get message details
`email_security.investigate.get(strpostfix_id, InvestigateGetParams**kwargs) -> InvestigateGetResponse`
**get** `/accounts/{account_id}/email-security/investigate/{postfix_id}`
Retrieves detailed information about a specific email message, including headers,
metadata, and security scan results.
### Parameters
- `account_id: str`
Account Identifier
- `postfix_id: str`
The identifier of the message.
### Returns
- `class InvestigateGetResponse: …`
- `id: str`
- `action_log: object`
- `client_recipients: List[str]`
- `detection_reasons: List[str]`
- `is_phish_submission: bool`
- `is_quarantined: bool`
- `postfix_id: str`
The identifier of the message.
- `properties: Properties`
- `allowlisted_pattern: Optional[str]`
- `allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `blocklisted_message: Optional[bool]`
- `blocklisted_pattern: Optional[str]`
- `whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `ts: str`
Deprecated, use `scanned_at` instead
- `alert_id: Optional[str]`
- `delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 8 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"REVIEW_SUBMISSION"`
- `"DMARC_UNVERIFIED"`
- `"DMARC_FAILURE_REPORT"`
- `"DMARC_AGGREGATE_REPORT"`
- `"THREAT_INTEL_SUBMISSION"`
- `"SIMULATION_SUBMISSION"`
- `"API"`
- `"RETRO_SCAN"`
- `edf_hash: Optional[str]`
- `envelope_from: Optional[str]`
- `envelope_to: Optional[List[str]]`
- `final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `findings: Optional[List[Finding]]`
- `attachment: Optional[str]`
- `detail: Optional[str]`
- `detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `field: Optional[str]`
- `name: Optional[str]`
- `portion: Optional[str]`
- `reason: Optional[str]`
- `score: Optional[float]`
- `value: Optional[str]`
- `from_: Optional[str]`
- `from_name: Optional[str]`
- `htmltext_structure_hash: Optional[str]`
- `message_id: Optional[str]`
- `post_delivery_operations: Optional[List[Literal["PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE"]]]`
- `"PREVIEW"`
- `"QUARANTINE_RELEASE"`
- `"SUBMISSION"`
- `"MOVE"`
- `postfix_id_outbound: Optional[str]`
- `replyto: Optional[str]`
- `scanned_at: Optional[datetime]`
- `sent_at: Optional[datetime]`
- `sent_date: Optional[str]`
Deprecated, use `sent_at` instead
- `subject: Optional[str]`
- `threat_categories: Optional[List[str]]`
- `to: Optional[List[str]]`
- `to_name: Optional[List[str]]`
- `validation: Optional[Validation]`
- `comment: Optional[str]`
- `dkim: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
investigate = client.email_security.investigate.get(
postfix_id="4Njp3P0STMz2c02Q",
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-2022-12-30T02:44:49-2a539d65",
"action_log": [],
"client_recipients": [
"email@example.com"
],
"detection_reasons": [
"Selector is a source of spam/uce : Smtp-Helo-Server-Ip=127.0.0[dot]186"
],
"is_phish_submission": false,
"is_quarantined": false,
"postfix_id": "47JJcT1w6GztQV7",
"properties": {
"allowlisted_pattern": "allowlisted_pattern",
"allowlisted_pattern_type": "quarantine_release",
"blocklisted_message": true,
"blocklisted_pattern": "blocklisted_pattern",
"whitelisted_pattern_type": "quarantine_release"
},
"ts": "2019-11-20T23:22:01",
"alert_id": "4Njp3P0STMz2c02Q-2022-12-30T02:44:49",
"delivery_mode": "DIRECT",
"edf_hash": null,
"envelope_from": "d1994@example.com",
"envelope_to": [
"email@example.com"
],
"final_disposition": "MALICIOUS",
"findings": [
{
"attachment": "attachment",
"detail": "detail",
"detection": "MALICIOUS",
"field": "field",
"name": "name",
"portion": "portion",
"reason": "reason",
"score": 0,
"value": "value"
}
],
"from": "d1994@example.com",
"from_name": "Sender Name",
"htmltext_structure_hash": null,
"message_id": "<4VAZPrAdg7IGNxdt1DWRNu0gvOeL_iZiwP4BQfo4DaE.Yw-woXuugQbeFhBpzwFQtqq_v2v1HOKznoMBqbciQpE@example.com>",
"post_delivery_operations": [
"PREVIEW"
],
"postfix_id_outbound": null,
"replyto": "email@example.com",
"scanned_at": "2019-11-20T23:22:01Z",
"sent_at": "2019-11-21T00:22:01Z",
"sent_date": "2019-11-21T00:22:01",
"subject": "listen, I highly recommend u to read that email, just to ensure not a thing will take place",
"threat_categories": [
"IPReputation",
"ASNReputation"
],
"to": [
"email@example.com"
],
"to_name": [
"Recipient Name"
],
"validation": {
"comment": null,
"dkim": "pass",
"dmarc": "none",
"spf": "fail"
}
},
"success": true
}
```
## Domain Types
### Investigate List Response
- `class InvestigateListResponse: …`
- `id: str`
- `action_log: object`
- `client_recipients: List[str]`
- `detection_reasons: List[str]`
- `is_phish_submission: bool`
- `is_quarantined: bool`
- `postfix_id: str`
The identifier of the message.
- `properties: Properties`
- `allowlisted_pattern: Optional[str]`
- `allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `blocklisted_message: Optional[bool]`
- `blocklisted_pattern: Optional[str]`
- `whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `ts: str`
Deprecated, use `scanned_at` instead
- `alert_id: Optional[str]`
- `delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 8 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"REVIEW_SUBMISSION"`
- `"DMARC_UNVERIFIED"`
- `"DMARC_FAILURE_REPORT"`
- `"DMARC_AGGREGATE_REPORT"`
- `"THREAT_INTEL_SUBMISSION"`
- `"SIMULATION_SUBMISSION"`
- `"API"`
- `"RETRO_SCAN"`
- `edf_hash: Optional[str]`
- `envelope_from: Optional[str]`
- `envelope_to: Optional[List[str]]`
- `final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `findings: Optional[List[Finding]]`
- `attachment: Optional[str]`
- `detail: Optional[str]`
- `detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `field: Optional[str]`
- `name: Optional[str]`
- `portion: Optional[str]`
- `reason: Optional[str]`
- `score: Optional[float]`
- `value: Optional[str]`
- `from_: Optional[str]`
- `from_name: Optional[str]`
- `htmltext_structure_hash: Optional[str]`
- `message_id: Optional[str]`
- `post_delivery_operations: Optional[List[Literal["PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE"]]]`
- `"PREVIEW"`
- `"QUARANTINE_RELEASE"`
- `"SUBMISSION"`
- `"MOVE"`
- `postfix_id_outbound: Optional[str]`
- `replyto: Optional[str]`
- `scanned_at: Optional[datetime]`
- `sent_at: Optional[datetime]`
- `sent_date: Optional[str]`
Deprecated, use `sent_at` instead
- `subject: Optional[str]`
- `threat_categories: Optional[List[str]]`
- `to: Optional[List[str]]`
- `to_name: Optional[List[str]]`
- `validation: Optional[Validation]`
- `comment: Optional[str]`
- `dkim: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
### Investigate Get Response
- `class InvestigateGetResponse: …`
- `id: str`
- `action_log: object`
- `client_recipients: List[str]`
- `detection_reasons: List[str]`
- `is_phish_submission: bool`
- `is_quarantined: bool`
- `postfix_id: str`
The identifier of the message.
- `properties: Properties`
- `allowlisted_pattern: Optional[str]`
- `allowlisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `blocklisted_message: Optional[bool]`
- `blocklisted_pattern: Optional[str]`
- `whitelisted_pattern_type: Optional[Literal["quarantine_release", "acceptable_sender", "allowed_sender", 5 more]]`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `ts: str`
Deprecated, use `scanned_at` instead
- `alert_id: Optional[str]`
- `delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 8 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"REVIEW_SUBMISSION"`
- `"DMARC_UNVERIFIED"`
- `"DMARC_FAILURE_REPORT"`
- `"DMARC_AGGREGATE_REPORT"`
- `"THREAT_INTEL_SUBMISSION"`
- `"SIMULATION_SUBMISSION"`
- `"API"`
- `"RETRO_SCAN"`
- `edf_hash: Optional[str]`
- `envelope_from: Optional[str]`
- `envelope_to: Optional[List[str]]`
- `final_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `findings: Optional[List[Finding]]`
- `attachment: Optional[str]`
- `detail: Optional[str]`
- `detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `field: Optional[str]`
- `name: Optional[str]`
- `portion: Optional[str]`
- `reason: Optional[str]`
- `score: Optional[float]`
- `value: Optional[str]`
- `from_: Optional[str]`
- `from_name: Optional[str]`
- `htmltext_structure_hash: Optional[str]`
- `message_id: Optional[str]`
- `post_delivery_operations: Optional[List[Literal["PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE"]]]`
- `"PREVIEW"`
- `"QUARANTINE_RELEASE"`
- `"SUBMISSION"`
- `"MOVE"`
- `postfix_id_outbound: Optional[str]`
- `replyto: Optional[str]`
- `scanned_at: Optional[datetime]`
- `sent_at: Optional[datetime]`
- `sent_date: Optional[str]`
Deprecated, use `sent_at` instead
- `subject: Optional[str]`
- `threat_categories: Optional[List[str]]`
- `to: Optional[List[str]]`
- `to_name: Optional[List[str]]`
- `validation: Optional[Validation]`
- `comment: Optional[str]`
- `dkim: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: Optional[Literal["pass", "neutral", "fail", 2 more]]`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
# Detections
## Get message detection details
`email_security.investigate.detections.get(strpostfix_id, DetectionGetParams**kwargs) -> DetectionGetResponse`
**get** `/accounts/{account_id}/email-security/investigate/{postfix_id}/detections`
Returns detection details such as threat categories and sender information for non-benign messages.
### Parameters
- `account_id: str`
Account Identifier
- `postfix_id: str`
The identifier of the message.
### Returns
- `class DetectionGetResponse: …`
- `action: str`
- `attachments: List[Attachment]`
- `size: int`
- `content_type: Optional[str]`
- `detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `encrypted: Optional[bool]`
- `name: 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: 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_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
detection = client.email_security.investigate.detections.get(
postfix_id="4Njp3P0STMz2c02Q",
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": "QUARANTINED",
"attachments": [
{
"size": 0,
"content_type": "content_type",
"detection": "MALICIOUS",
"encrypted": true,
"name": "name"
}
],
"headers": [
{
"name": "From",
"value": "Sender Name "
},
{
"name": "Subject",
"value": "listen, I highly recommend u to read that email, just to ensure not a thing will take place"
}
],
"links": [
{
"href": "https://example.com",
"text": "Click here!"
}
],
"sender_info": {
"as_name": "AS0",
"as_number": 0,
"geo": "US/-/-",
"ip": "127.0.0.1",
"pld": "example.com"
},
"threat_categories": [
{
"id": 1234,
"description": null,
"name": "IP Reputation"
}
],
"validation": {
"comment": null,
"dkim": "pass",
"dmarc": "none",
"spf": "fail"
},
"final_disposition": "MALICIOUS"
},
"success": true
}
```
## Domain Types
### Detection Get Response
- `class DetectionGetResponse: …`
- `action: str`
- `attachments: List[Attachment]`
- `size: int`
- `content_type: Optional[str]`
- `detection: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `encrypted: Optional[bool]`
- `name: 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: 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(strpostfix_id, PreviewGetParams**kwargs) -> PreviewGetResponse`
**get** `/accounts/{account_id}/email-security/investigate/{postfix_id}/preview`
Returns a preview of the message body as a base64 encoded PNG image for non-benign messages.
### Parameters
- `account_id: str`
Account Identifier
- `postfix_id: str`
The identifier of the message.
### Returns
- `class PreviewGetResponse: …`
- `screenshot: str`
A base64 encoded PNG image of the email.
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
preview = client.email_security.investigate.preview.get(
postfix_id="4Njp3P0STMz2c02Q",
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": "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"
},
"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 of an email message for safe viewing without executing any
embedded content.
### Parameters
- `account_id: str`
Account 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_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
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": "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"
},
"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(strpostfix_id, RawGetParams**kwargs) -> RawGetResponse`
**get** `/accounts/{account_id}/email-security/investigate/{postfix_id}/raw`
Returns the raw eml of any non-benign message.
### Parameters
- `account_id: str`
Account Identifier
- `postfix_id: str`
The identifier of the message.
### 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_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
raw = client.email_security.investigate.raw.get(
postfix_id="4Njp3P0STMz2c02Q",
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": "MIME-Version: 1.0\nContent-Type: text/plain; charset=\"utf-8\"\n\nFrom: sender@example.com\nTo: recipient@example.com\nSubject: Test Email\n\nThis is a test email."
},
"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(strpostfix_id, TraceGetParams**kwargs) -> TraceGetResponse`
**get** `/accounts/{account_id}/email-security/investigate/{postfix_id}/trace`
Gets the delivery trace for an email message, showing its path through email
security processing.
### Parameters
- `account_id: str`
Account Identifier
- `postfix_id: str`
The identifier of the message.
### Returns
- `class TraceGetResponse: …`
- `inbound: Inbound`
- `lines: Optional[List[InboundLine]]`
- `lineno: int`
- `message: str`
- `ts: datetime`
- `pending: Optional[bool]`
- `outbound: Outbound`
- `lines: Optional[List[OutboundLine]]`
- `lineno: int`
- `message: str`
- `ts: datetime`
- `pending: Optional[bool]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
trace = client.email_security.investigate.trace.get(
postfix_id="4Njp3P0STMz2c02Q",
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,
"message": "message",
"ts": "2019-12-27T18:11:19.117Z"
}
],
"pending": true
},
"outbound": {
"lines": [
{
"lineno": 0,
"message": "message",
"ts": "2019-12-27T18:11:19.117Z"
}
],
"pending": true
}
},
"success": true
}
```
## Domain Types
### Trace Get Response
- `class TraceGetResponse: …`
- `inbound: Inbound`
- `lines: Optional[List[InboundLine]]`
- `lineno: int`
- `message: str`
- `ts: datetime`
- `pending: Optional[bool]`
- `outbound: Outbound`
- `lines: Optional[List[OutboundLine]]`
- `lineno: int`
- `message: str`
- `ts: datetime`
- `pending: Optional[bool]`
# Move
## Move a message
`email_security.investigate.move.create(strpostfix_id, MoveCreateParams**kwargs) -> SyncSinglePage[MoveCreateResponse]`
**post** `/accounts/{account_id}/email-security/investigate/{postfix_id}/move`
Moves a single email message to a different folder or changes its quarantine status.
### Parameters
- `account_id: str`
Account Identifier
- `postfix_id: str`
The identifier of the message.
- `destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]`
- `"Inbox"`
- `"JunkEmail"`
- `"DeletedItems"`
- `"RecoverableItemsDeletions"`
- `"RecoverableItemsPurges"`
### Returns
- `class MoveCreateResponse: …`
- `completed_timestamp: datetime`
Deprecated, use `completed_at` instead
- `item_count: int`
- `success: bool`
- `completed_at: Optional[datetime]`
- `destination: Optional[str]`
- `message_id: Optional[str]`
- `operation: Optional[str]`
- `recipient: Optional[str]`
- `status: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.investigate.move.create(
postfix_id="4Njp3P0STMz2c02Q",
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": [
{
"completed_timestamp": "2019-12-27T18:11:19.117Z",
"item_count": 0,
"success": true,
"completed_at": "2019-12-27T18:11:19.117Z",
"destination": "destination",
"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`
Maximum batch size: 1000 messages per request
### Parameters
- `account_id: str`
Account Identifier
- `destination: Literal["Inbox", "JunkEmail", "DeletedItems", 2 more]`
- `"Inbox"`
- `"JunkEmail"`
- `"DeletedItems"`
- `"RecoverableItemsDeletions"`
- `"RecoverableItemsPurges"`
- `ids: Optional[SequenceNotStr[str]]`
List of message IDs to move.
- `postfix_ids: Optional[SequenceNotStr[str]]`
Deprecated: Use `ids` instead. List of message IDs to move.
### Returns
- `class MoveBulkResponse: …`
- `completed_timestamp: datetime`
Deprecated, use `completed_at` instead
- `item_count: int`
- `success: bool`
- `completed_at: Optional[datetime]`
- `destination: Optional[str]`
- `message_id: Optional[str]`
- `operation: Optional[str]`
- `recipient: Optional[str]`
- `status: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.investigate.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": [
{
"completed_timestamp": "2019-12-27T18:11:19.117Z",
"item_count": 0,
"success": true,
"completed_at": "2019-12-27T18:11:19.117Z",
"destination": "destination",
"message_id": "message_id",
"operation": "operation",
"recipient": "recipient",
"status": "status"
}
],
"success": true
}
```
## Domain Types
### Move Create Response
- `class MoveCreateResponse: …`
- `completed_timestamp: datetime`
Deprecated, use `completed_at` instead
- `item_count: int`
- `success: bool`
- `completed_at: Optional[datetime]`
- `destination: Optional[str]`
- `message_id: Optional[str]`
- `operation: Optional[str]`
- `recipient: Optional[str]`
- `status: Optional[str]`
### Move Bulk Response
- `class MoveBulkResponse: …`
- `completed_timestamp: datetime`
Deprecated, use `completed_at` instead
- `item_count: int`
- `success: bool`
- `completed_at: Optional[datetime]`
- `destination: Optional[str]`
- `message_id: Optional[str]`
- `operation: Optional[str]`
- `recipient: Optional[str]`
- `status: Optional[str]`
# Reclassify
## Change email classification
`email_security.investigate.reclassify.create(strpostfix_id, ReclassifyCreateParams**kwargs) -> object`
**post** `/accounts/{account_id}/email-security/investigate/{postfix_id}/reclassify`
Submits an email message for reclassification, updating its threat assessment
based on new analysis.
### Parameters
- `account_id: str`
Account Identifier
- `postfix_id: str`
The identifier of the message.
- `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_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
reclassify = client.email_security.investigate.reclassify.create(
postfix_id="4Njp3P0STMz2c02Q",
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 a quarantined email message, allowing it to be delivered to the recipient.
### Parameters
- `account_id: str`
Account Identifier
- `body: SequenceNotStr[str]`
A list of messages identfied by their `postfix_id`s that should be released.
### Returns
- `class ReleaseBulkResponse: …`
- `id: str`
- `postfix_id: str`
The identifier of the message.
- `delivered: Optional[List[str]]`
- `failed: Optional[List[str]]`
- `undelivered: Optional[List[str]]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.investigate.release.bulk(
account_id="023e105f4ecef8ad9ca31a8372d0c353",
body=["4Njp3P0STMz2c02Q"],
)
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": "id",
"postfix_id": "4Njp3P0STMz2c02Q",
"delivered": [
"string"
],
"failed": [
"string"
],
"undelivered": [
"string"
]
}
],
"success": true
}
```
## Domain Types
### Release Bulk Response
- `class ReleaseBulkResponse: …`
- `id: str`
- `postfix_id: str`
The identifier of the message.
- `delivered: Optional[List[str]]`
- `failed: Optional[List[str]]`
- `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` reports showing phishing attempts and suspicious email patterns
detected.
### Parameters
- `account_id: str`
Account Identifier
- `end: Optional[Union[str, datetime]]`
The end of the search date range (RFC3339 format).
- `from_date: Optional[Union[null, null]]`
- `start: Optional[Union[str, datetime]]`
The beginning of the search date range (RFC3339 format).
- `to_date: Optional[Union[null, null]]`
### Returns
- `class ReportListResponse: …`
- `id: int`
- `content: str`
- `created_at: datetime`
- `disposition: Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `fields: Fields`
- `to: List[str]`
- `ts: datetime`
- `from_: Optional[str]`
- `postfix_id: Optional[str]`
- `priority: str`
- `title: str`
- `ts: datetime`
- `updated_at: datetime`
- `tags: Optional[List[Tag]]`
- `category: str`
- `value: str`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.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",
"created_at": "2019-12-27T18:11:19.117Z",
"disposition": "MALICIOUS",
"fields": {
"to": [
"string"
],
"ts": "2019-12-27T18:11:19.117Z",
"from": "from",
"postfix_id": "postfix_id"
},
"priority": "priority",
"title": "title",
"ts": "2019-12-27T18:11:19.117Z",
"updated_at": "2019-12-27T18:11:19.117Z",
"tags": [
{
"category": "category",
"value": "value"
}
]
}
],
"success": true
}
```
## Domain Types
### Report List Response
- `class ReportListResponse: …`
- `id: int`
- `content: str`
- `created_at: datetime`
- `disposition: Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `fields: Fields`
- `to: List[str]`
- `ts: datetime`
- `from_: Optional[str]`
- `postfix_id: Optional[str]`
- `priority: str`
- `title: str`
- `ts: datetime`
- `updated_at: datetime`
- `tags: Optional[List[Tag]]`
- `category: str`
- `value: str`
# 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`
Lists, searches, and sorts an account’s email allow policies.
### Parameters
- `account_id: str`
Account Identifier
- `direction: Optional[Literal["asc", "desc"]]`
The sorting direction.
- `"asc"`
- `"desc"`
- `is_acceptable_sender: Optional[bool]`
- `is_exempt_recipient: Optional[bool]`
- `is_recipient: Optional[bool]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
- `is_trusted_sender: Optional[bool]`
- `order: Optional[Literal["pattern", "created_at"]]`
The field to sort by.
- `"pattern"`
- `"created_at"`
- `page: Optional[int]`
The page number of paginated results.
- `pattern: Optional[str]`
- `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `per_page: Optional[int]`
The number of results per page.
- `search: Optional[str]`
Allows searching in multiple properties of a record simultaneously.
This parameter is intended for human users, not automation. Its exact
behavior is intentionally left unspecified and is subject to change
in the future.
- `verify_sender: Optional[bool]`
### Returns
- `class AllowPolicyListResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"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]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.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"
}
}
],
"result": [
{
"id": 2401,
"created_at": "2019-12-27T18:11:19.117Z",
"is_acceptable_sender": true,
"is_exempt_recipient": true,
"is_regex": true,
"is_trusted_sender": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"pattern_type": "EMAIL",
"verify_sender": true,
"comments": "comments",
"is_recipient": true,
"is_sender": true,
"is_spoof": true
}
],
"result_info": {
"count": 1,
"page": 1,
"per_page": 20,
"total_count": 2000
},
"success": true
}
```
## Get an email allow policy
`email_security.settings.allow_policies.get(intpolicy_id, AllowPolicyGetParams**kwargs) -> AllowPolicyGetResponse`
**get** `/accounts/{account_id}/email-security/settings/allow_policies/{policy_id}`
Retrieves details for a specific email allow policy, including its matching criteria
and scope.
### Parameters
- `account_id: str`
Account Identifier
- `policy_id: int`
The unique identifier for the allow policy.
### Returns
- `class AllowPolicyGetResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"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]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
allow_policy = client.email_security.settings.allow_policies.get(
policy_id=2401,
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"
}
}
],
"result": {
"id": 2401,
"created_at": "2019-12-27T18:11:19.117Z",
"is_acceptable_sender": true,
"is_exempt_recipient": true,
"is_regex": true,
"is_trusted_sender": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"pattern_type": "EMAIL",
"verify_sender": true,
"comments": "comments",
"is_recipient": true,
"is_sender": true,
"is_spoof": true
},
"success": true
}
```
## Create an email allow policy
`email_security.settings.allow_policies.create(AllowPolicyCreateParams**kwargs) -> AllowPolicyCreateResponse`
**post** `/accounts/{account_id}/email-security/settings/allow_policies`
Creates a new email allow policy that permits specific senders, domains, or patterns
to bypass security scanning.
### Parameters
- `account_id: str`
Account 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"]`
- `"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]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
### Returns
- `class AllowPolicyCreateResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"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]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
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"
}
}
],
"result": {
"id": 2401,
"created_at": "2019-12-27T18:11:19.117Z",
"is_acceptable_sender": true,
"is_exempt_recipient": true,
"is_regex": true,
"is_trusted_sender": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"pattern_type": "EMAIL",
"verify_sender": true,
"comments": "comments",
"is_recipient": true,
"is_sender": true,
"is_spoof": true
},
"success": true
}
```
## Update an email allow policy
`email_security.settings.allow_policies.edit(intpolicy_id, AllowPolicyEditParams**kwargs) -> AllowPolicyEditResponse`
**patch** `/accounts/{account_id}/email-security/settings/allow_policies/{policy_id}`
Updates an existing email allow policy, modifying its matching criteria or scope.
### Parameters
- `account_id: str`
Account Identifier
- `policy_id: int`
The unique identifier for the allow policy.
- `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_regex: Optional[bool]`
- `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"]]`
- `"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: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"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]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
response = client.email_security.settings.allow_policies.edit(
policy_id=2401,
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"
}
}
],
"result": {
"id": 2401,
"created_at": "2019-12-27T18:11:19.117Z",
"is_acceptable_sender": true,
"is_exempt_recipient": true,
"is_regex": true,
"is_trusted_sender": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"pattern_type": "EMAIL",
"verify_sender": true,
"comments": "comments",
"is_recipient": true,
"is_sender": true,
"is_spoof": true
},
"success": true
}
```
## Delete an email allow policy
`email_security.settings.allow_policies.delete(intpolicy_id, AllowPolicyDeleteParams**kwargs) -> AllowPolicyDeleteResponse`
**delete** `/accounts/{account_id}/email-security/settings/allow_policies/{policy_id}`
Removes an email allow policy. Previously allowed senders will be subject to normal
security scanning.
### Parameters
- `account_id: str`
Account Identifier
- `policy_id: int`
The unique identifier for the allow policy.
### Returns
- `class AllowPolicyDeleteResponse: …`
- `id: int`
The unique identifier for the allow policy.
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
allow_policy = client.email_security.settings.allow_policies.delete(
policy_id=2401,
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"
}
}
],
"result": {
"id": 2401
},
"success": true
}
```
## Domain Types
### Allow Policy List Response
- `class AllowPolicyListResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"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]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
### Allow Policy Get Response
- `class AllowPolicyGetResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"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]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
### Allow Policy Create Response
- `class AllowPolicyCreateResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"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]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
### Allow Policy Edit Response
- `class AllowPolicyEditResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"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]`
- `is_sender: Optional[bool]`
- `is_spoof: Optional[bool]`
### Allow Policy Delete Response
- `class AllowPolicyDeleteResponse: …`
- `id: int`
The unique identifier for the allow policy.
# 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`
Lists all blocked sender entries with their patterns and block reasons.
### Parameters
- `account_id: str`
Account Identifier
- `direction: Optional[Literal["asc", "desc"]]`
The sorting direction.
- `"asc"`
- `"desc"`
- `order: Optional[Literal["pattern", "created_at"]]`
The field to sort by.
- `"pattern"`
- `"created_at"`
- `page: Optional[int]`
The page number of paginated results.
- `pattern: Optional[str]`
- `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `per_page: Optional[int]`
The number of results per page.
- `search: Optional[str]`
Allows searching in multiple properties of a record simultaneously.
This parameter is intended for human users, not automation. Its exact
behavior is intentionally left unspecified and is subject to change
in the future.
### Returns
- `class BlockSenderListResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `is_regex: bool`
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.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"
}
}
],
"result": [
{
"id": 2402,
"created_at": "2019-12-27T18:11:19.117Z",
"is_regex": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"pattern_type": "EMAIL",
"comments": "comments"
}
],
"result_info": {
"count": 1,
"page": 1,
"per_page": 20,
"total_count": 2000
},
"success": true
}
```
## Get a blocked email sender
`email_security.settings.block_senders.get(intpattern_id, BlockSenderGetParams**kwargs) -> BlockSenderGetResponse`
**get** `/accounts/{account_id}/email-security/settings/block_senders/{pattern_id}`
Gets information about a specific blocked sender entry, including the pattern and
block reason.
### Parameters
- `account_id: str`
Account Identifier
- `pattern_id: int`
The unique identifier for the allow policy.
### Returns
- `class BlockSenderGetResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `is_regex: bool`
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
block_sender = client.email_security.settings.block_senders.get(
pattern_id=2402,
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"
}
}
],
"result": {
"id": 2402,
"created_at": "2019-12-27T18:11:19.117Z",
"is_regex": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"pattern_type": "EMAIL",
"comments": "comments"
},
"success": true
}
```
## Create a blocked email sender
`email_security.settings.block_senders.create(BlockSenderCreateParams**kwargs) -> BlockSenderCreateResponse`
**post** `/accounts/{account_id}/email-security/settings/block_senders`
Adds a sender pattern to the email block list, preventing messages from matching
senders from being delivered.
### Parameters
- `account_id: str`
Account Identifier
- `is_regex: bool`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: Optional[str]`
### Returns
- `class BlockSenderCreateResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `is_regex: bool`
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
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"
}
}
],
"result": {
"id": 2402,
"created_at": "2019-12-27T18:11:19.117Z",
"is_regex": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"pattern_type": "EMAIL",
"comments": "comments"
},
"success": true
}
```
## Update a blocked email sender
`email_security.settings.block_senders.edit(intpattern_id, BlockSenderEditParams**kwargs) -> BlockSenderEditResponse`
**patch** `/accounts/{account_id}/email-security/settings/block_senders/{pattern_id}`
Modifies a blocked sender entry, updating its pattern or block reason.
### Parameters
- `account_id: str`
Account Identifier
- `pattern_id: int`
The unique identifier for the allow policy.
- `comments: Optional[str]`
- `is_regex: Optional[bool]`
- `pattern: Optional[str]`
- `pattern_type: Optional[Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
### Returns
- `class BlockSenderEditResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `is_regex: bool`
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
response = client.email_security.settings.block_senders.edit(
pattern_id=2402,
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"
}
}
],
"result": {
"id": 2402,
"created_at": "2019-12-27T18:11:19.117Z",
"is_regex": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"pattern_type": "EMAIL",
"comments": "comments"
},
"success": true
}
```
## Delete a blocked email sender
`email_security.settings.block_senders.delete(intpattern_id, BlockSenderDeleteParams**kwargs) -> BlockSenderDeleteResponse`
**delete** `/accounts/{account_id}/email-security/settings/block_senders/{pattern_id}`
Removes a sender from the email block list, allowing their messages to be delivered
normally.
### Parameters
- `account_id: str`
Account Identifier
- `pattern_id: int`
The unique identifier for the allow policy.
### Returns
- `class BlockSenderDeleteResponse: …`
- `id: int`
The unique identifier for the allow policy.
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
block_sender = client.email_security.settings.block_senders.delete(
pattern_id=2402,
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"
}
}
],
"result": {
"id": 2402
},
"success": true
}
```
## Domain Types
### Block Sender List Response
- `class BlockSenderListResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `is_regex: bool`
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: Optional[str]`
### Block Sender Get Response
- `class BlockSenderGetResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `is_regex: bool`
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: Optional[str]`
### Block Sender Create Response
- `class BlockSenderCreateResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `is_regex: bool`
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: Optional[str]`
### Block Sender Edit Response
- `class BlockSenderEditResponse: …`
- `id: int`
The unique identifier for the allow policy.
- `created_at: datetime`
- `is_regex: bool`
- `last_modified: datetime`
- `pattern: str`
- `pattern_type: Literal["EMAIL", "DOMAIN", "IP", "UNKNOWN"]`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: Optional[str]`
### Block Sender Delete Response
- `class BlockSenderDeleteResponse: …`
- `id: int`
The unique identifier for the allow policy.
# Domains
## List protected email domains
`email_security.settings.domains.list(DomainListParams**kwargs) -> SyncV4PagePaginationArray[DomainListResponse]`
**get** `/accounts/{account_id}/email-security/settings/domains`
Lists, searches, and sorts an account’s email domains.
### Parameters
- `account_id: str`
Account Identifier
- `active_delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]`
Filters response to domains with the currently active delivery mode.
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `allowed_delivery_mode: Optional[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]`
Filters response to domains with the provided delivery mode.
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `direction: Optional[Literal["asc", "desc"]]`
The sorting direction.
- `"asc"`
- `"desc"`
- `domain: Optional[SequenceNotStr[str]]`
Filters results by the provided domains, allowing for multiple occurrences.
- `integration_id: Optional[str]`
Filters response to domains with the provided integration ID.
- `order: Optional[Literal["domain", "created_at"]]`
The field to sort by.
- `"domain"`
- `"created_at"`
- `page: Optional[int]`
The page number of paginated results.
- `per_page: Optional[int]`
The number of results per page.
- `search: Optional[str]`
Allows searching in multiple properties of a record simultaneously.
This parameter is intended for human users, not automation. Its exact
behavior is intentionally left unspecified and is subject to change
in the future.
### Returns
- `class DomainListResponse: …`
- `id: int`
The unique identifier for the domain.
- `allowed_delivery_modes: List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: datetime`
- `domain: str`
- `drop_dispositions: List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: List[str]`
- `last_modified: datetime`
- `lookback_hops: int`
- `regions: List[Literal["GLOBAL", "AU", "DE", 2 more]]`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: str`
- `authorization: Optional[Authorization]`
- `authorized: bool`
- `timestamp: datetime`
- `status_message: Optional[str]`
- `dmarc_status: Optional[Literal["none", "good", "invalid"]]`
- `"none"`
- `"good"`
- `"invalid"`
- `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]`
- `o365_tenant_id: Optional[str]`
- `require_tls_inbound: Optional[bool]`
- `require_tls_outbound: Optional[bool]`
- `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.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"
}
}
],
"result": [
{
"id": 2400,
"allowed_delivery_modes": [
"API"
],
"created_at": "2023-11-14T22:13:20Z",
"domain": "example.com",
"drop_dispositions": [
"MALICIOUS",
"SPAM"
],
"ip_restrictions": [
"string"
],
"last_modified": "2023-11-14T22:13:20Z",
"lookback_hops": 2,
"regions": [
"GLOBAL"
],
"transport": "example.com",
"authorization": {
"authorized": true,
"timestamp": "2019-12-27T18:11:19.117Z",
"status_message": "status_message"
},
"dmarc_status": "good",
"emails_processed": {
"timestamp": "2019-12-27T18:11:19.117Z",
"total_emails_processed": 0,
"total_emails_processed_previous": 0
},
"folder": "Inbox",
"inbox_provider": "Microsoft",
"integration_id": "a5dbb180-60ea-4578-84bb-d01a5d4e50c3",
"o365_tenant_id": "c3c3239d-8858-47df-9618-0e2d9bdf6aa8",
"require_tls_inbound": false,
"require_tls_outbound": true,
"spf_status": "good"
}
],
"result_info": {
"count": 1,
"page": 1,
"per_page": 20,
"total_count": 2000
},
"success": true
}
```
## Get an email domain
`email_security.settings.domains.get(intdomain_id, DomainGetParams**kwargs) -> DomainGetResponse`
**get** `/accounts/{account_id}/email-security/settings/domains/{domain_id}`
Gets configuration details for a specific domain in email security.
### Parameters
- `account_id: str`
Account Identifier
- `domain_id: int`
The unique identifier for the domain.
### Returns
- `class DomainGetResponse: …`
- `id: int`
The unique identifier for the domain.
- `allowed_delivery_modes: List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: datetime`
- `domain: str`
- `drop_dispositions: List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: List[str]`
- `last_modified: datetime`
- `lookback_hops: int`
- `regions: List[Literal["GLOBAL", "AU", "DE", 2 more]]`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: str`
- `authorization: Optional[Authorization]`
- `authorized: bool`
- `timestamp: datetime`
- `status_message: Optional[str]`
- `dmarc_status: Optional[Literal["none", "good", "invalid"]]`
- `"none"`
- `"good"`
- `"invalid"`
- `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]`
- `o365_tenant_id: Optional[str]`
- `require_tls_inbound: Optional[bool]`
- `require_tls_outbound: Optional[bool]`
- `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
domain = client.email_security.settings.domains.get(
domain_id=2400,
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"
}
}
],
"result": {
"id": 2400,
"allowed_delivery_modes": [
"API"
],
"created_at": "2023-11-14T22:13:20Z",
"domain": "example.com",
"drop_dispositions": [
"MALICIOUS",
"SPAM"
],
"ip_restrictions": [
"string"
],
"last_modified": "2023-11-14T22:13:20Z",
"lookback_hops": 2,
"regions": [
"GLOBAL"
],
"transport": "example.com",
"authorization": {
"authorized": true,
"timestamp": "2019-12-27T18:11:19.117Z",
"status_message": "status_message"
},
"dmarc_status": "good",
"emails_processed": {
"timestamp": "2019-12-27T18:11:19.117Z",
"total_emails_processed": 0,
"total_emails_processed_previous": 0
},
"folder": "Inbox",
"inbox_provider": "Microsoft",
"integration_id": "a5dbb180-60ea-4578-84bb-d01a5d4e50c3",
"o365_tenant_id": "c3c3239d-8858-47df-9618-0e2d9bdf6aa8",
"require_tls_inbound": false,
"require_tls_outbound": true,
"spf_status": "good"
},
"success": true
}
```
## Update an email domain
`email_security.settings.domains.edit(intdomain_id, DomainEditParams**kwargs) -> DomainEditResponse`
**patch** `/accounts/{account_id}/email-security/settings/domains/{domain_id}`
Updates configuration for a domain in email security.
### Parameters
- `account_id: str`
Account Identifier
- `domain_id: int`
The unique identifier for the domain.
- `ip_restrictions: SequenceNotStr[str]`
- `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]`
- `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: int`
The unique identifier for the domain.
- `allowed_delivery_modes: List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: datetime`
- `domain: str`
- `drop_dispositions: List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: List[str]`
- `last_modified: datetime`
- `lookback_hops: int`
- `regions: List[Literal["GLOBAL", "AU", "DE", 2 more]]`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: str`
- `authorization: Optional[Authorization]`
- `authorized: bool`
- `timestamp: datetime`
- `status_message: Optional[str]`
- `dmarc_status: Optional[Literal["none", "good", "invalid"]]`
- `"none"`
- `"good"`
- `"invalid"`
- `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]`
- `o365_tenant_id: Optional[str]`
- `require_tls_inbound: Optional[bool]`
- `require_tls_outbound: Optional[bool]`
- `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
response = client.email_security.settings.domains.edit(
domain_id=2400,
account_id="023e105f4ecef8ad9ca31a8372d0c353",
ip_restrictions=["192.0.2.0/24", "2001:db8::/32"],
)
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"
}
}
],
"result": {
"id": 2400,
"allowed_delivery_modes": [
"API"
],
"created_at": "2023-11-14T22:13:20Z",
"domain": "example.com",
"drop_dispositions": [
"MALICIOUS",
"SPAM"
],
"ip_restrictions": [
"string"
],
"last_modified": "2023-11-14T22:13:20Z",
"lookback_hops": 2,
"regions": [
"GLOBAL"
],
"transport": "example.com",
"authorization": {
"authorized": true,
"timestamp": "2019-12-27T18:11:19.117Z",
"status_message": "status_message"
},
"dmarc_status": "good",
"emails_processed": {
"timestamp": "2019-12-27T18:11:19.117Z",
"total_emails_processed": 0,
"total_emails_processed_previous": 0
},
"folder": "Inbox",
"inbox_provider": "Microsoft",
"integration_id": "a5dbb180-60ea-4578-84bb-d01a5d4e50c3",
"o365_tenant_id": "c3c3239d-8858-47df-9618-0e2d9bdf6aa8",
"require_tls_inbound": false,
"require_tls_outbound": true,
"spf_status": "good"
},
"success": true
}
```
## Unprotect an email domain
`email_security.settings.domains.delete(intdomain_id, DomainDeleteParams**kwargs) -> DomainDeleteResponse`
**delete** `/accounts/{account_id}/email-security/settings/domains/{domain_id}`
Unprotect an email domain
### Parameters
- `account_id: str`
Account Identifier
- `domain_id: int`
The unique identifier for the domain.
### Returns
- `class DomainDeleteResponse: …`
- `id: int`
The unique identifier for the domain.
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
domain = client.email_security.settings.domains.delete(
domain_id=2400,
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"
}
}
],
"result": {
"id": 2400
},
"success": true
}
```
## Unprotect multiple email domains
`email_security.settings.domains.bulk_delete(DomainBulkDeleteParams**kwargs) -> SyncSinglePage[DomainBulkDeleteResponse]`
**delete** `/accounts/{account_id}/email-security/settings/domains`
Bulk removes multiple domains from email security configuration in a single request.
### Parameters
- `account_id: str`
Account Identifier
### Returns
- `class DomainBulkDeleteResponse: …`
- `id: int`
The unique identifier for the domain.
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.settings.domains.bulk_delete(
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": 2400
}
],
"success": true
}
```
## Domain Types
### Domain List Response
- `class DomainListResponse: …`
- `id: int`
The unique identifier for the domain.
- `allowed_delivery_modes: List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: datetime`
- `domain: str`
- `drop_dispositions: List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: List[str]`
- `last_modified: datetime`
- `lookback_hops: int`
- `regions: List[Literal["GLOBAL", "AU", "DE", 2 more]]`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: str`
- `authorization: Optional[Authorization]`
- `authorized: bool`
- `timestamp: datetime`
- `status_message: Optional[str]`
- `dmarc_status: Optional[Literal["none", "good", "invalid"]]`
- `"none"`
- `"good"`
- `"invalid"`
- `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]`
- `o365_tenant_id: Optional[str]`
- `require_tls_inbound: Optional[bool]`
- `require_tls_outbound: Optional[bool]`
- `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
### Domain Get Response
- `class DomainGetResponse: …`
- `id: int`
The unique identifier for the domain.
- `allowed_delivery_modes: List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: datetime`
- `domain: str`
- `drop_dispositions: List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: List[str]`
- `last_modified: datetime`
- `lookback_hops: int`
- `regions: List[Literal["GLOBAL", "AU", "DE", 2 more]]`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: str`
- `authorization: Optional[Authorization]`
- `authorized: bool`
- `timestamp: datetime`
- `status_message: Optional[str]`
- `dmarc_status: Optional[Literal["none", "good", "invalid"]]`
- `"none"`
- `"good"`
- `"invalid"`
- `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]`
- `o365_tenant_id: Optional[str]`
- `require_tls_inbound: Optional[bool]`
- `require_tls_outbound: Optional[bool]`
- `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
### Domain Edit Response
- `class DomainEditResponse: …`
- `id: int`
The unique identifier for the domain.
- `allowed_delivery_modes: List[Literal["DIRECT", "BCC", "JOURNAL", 2 more]]`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: datetime`
- `domain: str`
- `drop_dispositions: List[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: List[str]`
- `last_modified: datetime`
- `lookback_hops: int`
- `regions: List[Literal["GLOBAL", "AU", "DE", 2 more]]`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: str`
- `authorization: Optional[Authorization]`
- `authorized: bool`
- `timestamp: datetime`
- `status_message: Optional[str]`
- `dmarc_status: Optional[Literal["none", "good", "invalid"]]`
- `"none"`
- `"good"`
- `"invalid"`
- `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]`
- `o365_tenant_id: Optional[str]`
- `require_tls_inbound: Optional[bool]`
- `require_tls_outbound: Optional[bool]`
- `spf_status: Optional[Literal["none", "good", "neutral", 2 more]]`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
### Domain Delete Response
- `class DomainDeleteResponse: …`
- `id: int`
The unique identifier for the domain.
### Domain Bulk Delete Response
- `class DomainBulkDeleteResponse: …`
- `id: int`
The unique identifier for the domain.
# 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`
Lists, searches, and sorts entries in the impersonation registry.
### Parameters
- `account_id: str`
Account Identifier
- `direction: Optional[Literal["asc", "desc"]]`
The sorting direction.
- `"asc"`
- `"desc"`
- `order: Optional[Literal["name", "email", "created_at"]]`
The field to sort by.
- `"name"`
- `"email"`
- `"created_at"`
- `page: Optional[int]`
The page number of paginated results.
- `per_page: Optional[int]`
The number of results per page.
- `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]`
Allows searching in multiple properties of a record simultaneously.
This parameter is intended for human users, not automation. Its exact
behavior is intentionally left unspecified and is subject to change
in the future.
### Returns
- `class ImpersonationRegistryListResponse: …`
- `id: int`
- `created_at: datetime`
- `email: str`
- `is_email_regex: bool`
- `last_modified: datetime`
- `name: str`
- `comments: Optional[str]`
- `directory_id: Optional[int]`
- `directory_node_id: Optional[int]`
- `external_directory_node_id: Optional[str]`
- `provenance: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.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"
}
}
],
"result": [
{
"id": 2403,
"created_at": "2019-12-27T18:11:19.117Z",
"email": "email",
"is_email_regex": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"name": "name",
"comments": "comments",
"directory_id": 0,
"directory_node_id": 0,
"external_directory_node_id": "external_directory_node_id",
"provenance": "provenance"
}
],
"result_info": {
"count": 1,
"page": 1,
"per_page": 20,
"total_count": 2000
},
"success": true
}
```
## Get an entry in impersonation registry
`email_security.settings.impersonation_registry.get(intdisplay_name_id, ImpersonationRegistryGetParams**kwargs) -> ImpersonationRegistryGetResponse`
**get** `/accounts/{account_id}/email-security/settings/impersonation_registry/{display_name_id}`
Retrieves a display name entry used for impersonation protection.
### Parameters
- `account_id: str`
Account Identifier
- `display_name_id: int`
### Returns
- `class ImpersonationRegistryGetResponse: …`
- `id: int`
- `created_at: datetime`
- `email: str`
- `is_email_regex: bool`
- `last_modified: datetime`
- `name: str`
- `comments: Optional[str]`
- `directory_id: Optional[int]`
- `directory_node_id: Optional[int]`
- `external_directory_node_id: Optional[str]`
- `provenance: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
impersonation_registry = client.email_security.settings.impersonation_registry.get(
display_name_id=2403,
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"
}
}
],
"result": {
"id": 2403,
"created_at": "2019-12-27T18:11:19.117Z",
"email": "email",
"is_email_regex": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"name": "name",
"comments": "comments",
"directory_id": 0,
"directory_node_id": 0,
"external_directory_node_id": "external_directory_node_id",
"provenance": "provenance"
},
"success": true
}
```
## Create an entry in impersonation registry
`email_security.settings.impersonation_registry.create(ImpersonationRegistryCreateParams**kwargs) -> ImpersonationRegistryCreateResponse`
**post** `/accounts/{account_id}/email-security/settings/impersonation_registry`
Creates a display name entry for email security impersonation protection.
### Parameters
- `account_id: str`
Account Identifier
- `email: str`
- `is_email_regex: bool`
- `name: str`
### Returns
- `class ImpersonationRegistryCreateResponse: …`
- `id: int`
- `created_at: datetime`
- `email: str`
- `is_email_regex: bool`
- `last_modified: datetime`
- `name: str`
- `comments: Optional[str]`
- `directory_id: Optional[int]`
- `directory_node_id: Optional[int]`
- `external_directory_node_id: Optional[str]`
- `provenance: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
impersonation_registry = client.email_security.settings.impersonation_registry.create(
account_id="023e105f4ecef8ad9ca31a8372d0c353",
email="email",
is_email_regex=True,
name="name",
)
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"
}
}
],
"result": {
"id": 2403,
"created_at": "2019-12-27T18:11:19.117Z",
"email": "email",
"is_email_regex": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"name": "name",
"comments": "comments",
"directory_id": 0,
"directory_node_id": 0,
"external_directory_node_id": "external_directory_node_id",
"provenance": "provenance"
},
"success": true
}
```
## Update an entry in impersonation registry
`email_security.settings.impersonation_registry.edit(intdisplay_name_id, ImpersonationRegistryEditParams**kwargs) -> ImpersonationRegistryEditResponse`
**patch** `/accounts/{account_id}/email-security/settings/impersonation_registry/{display_name_id}`
Updates a display name entry used for impersonation protection.
### Parameters
- `account_id: str`
Account Identifier
- `display_name_id: int`
- `email: Optional[str]`
- `is_email_regex: Optional[bool]`
- `name: Optional[str]`
### Returns
- `class ImpersonationRegistryEditResponse: …`
- `id: int`
- `created_at: datetime`
- `email: str`
- `is_email_regex: bool`
- `last_modified: datetime`
- `name: str`
- `comments: Optional[str]`
- `directory_id: Optional[int]`
- `directory_node_id: Optional[int]`
- `external_directory_node_id: Optional[str]`
- `provenance: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
response = client.email_security.settings.impersonation_registry.edit(
display_name_id=2403,
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"
}
}
],
"result": {
"id": 2403,
"created_at": "2019-12-27T18:11:19.117Z",
"email": "email",
"is_email_regex": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"name": "name",
"comments": "comments",
"directory_id": 0,
"directory_node_id": 0,
"external_directory_node_id": "external_directory_node_id",
"provenance": "provenance"
},
"success": true
}
```
## Delete an entry from impersonation registry
`email_security.settings.impersonation_registry.delete(intdisplay_name_id, ImpersonationRegistryDeleteParams**kwargs) -> ImpersonationRegistryDeleteResponse`
**delete** `/accounts/{account_id}/email-security/settings/impersonation_registry/{display_name_id}`
Removes a display name from impersonation protection monitoring.
### Parameters
- `account_id: str`
Account Identifier
- `display_name_id: int`
### Returns
- `class ImpersonationRegistryDeleteResponse: …`
- `id: int`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
impersonation_registry = client.email_security.settings.impersonation_registry.delete(
display_name_id=2403,
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"
}
}
],
"result": {
"id": 2403
},
"success": true
}
```
## Domain Types
### Impersonation Registry List Response
- `class ImpersonationRegistryListResponse: …`
- `id: int`
- `created_at: datetime`
- `email: str`
- `is_email_regex: bool`
- `last_modified: datetime`
- `name: str`
- `comments: Optional[str]`
- `directory_id: Optional[int]`
- `directory_node_id: Optional[int]`
- `external_directory_node_id: Optional[str]`
- `provenance: Optional[str]`
### Impersonation Registry Get Response
- `class ImpersonationRegistryGetResponse: …`
- `id: int`
- `created_at: datetime`
- `email: str`
- `is_email_regex: bool`
- `last_modified: datetime`
- `name: str`
- `comments: Optional[str]`
- `directory_id: Optional[int]`
- `directory_node_id: Optional[int]`
- `external_directory_node_id: Optional[str]`
- `provenance: Optional[str]`
### Impersonation Registry Create Response
- `class ImpersonationRegistryCreateResponse: …`
- `id: int`
- `created_at: datetime`
- `email: str`
- `is_email_regex: bool`
- `last_modified: datetime`
- `name: str`
- `comments: Optional[str]`
- `directory_id: Optional[int]`
- `directory_node_id: Optional[int]`
- `external_directory_node_id: Optional[str]`
- `provenance: Optional[str]`
### Impersonation Registry Edit Response
- `class ImpersonationRegistryEditResponse: …`
- `id: int`
- `created_at: datetime`
- `email: str`
- `is_email_regex: bool`
- `last_modified: datetime`
- `name: str`
- `comments: Optional[str]`
- `directory_id: Optional[int]`
- `directory_node_id: Optional[int]`
- `external_directory_node_id: Optional[str]`
- `provenance: Optional[str]`
### Impersonation Registry Delete Response
- `class ImpersonationRegistryDeleteResponse: …`
- `id: int`
# 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`
Lists, searches, and sorts an account’s trusted email domains.
### Parameters
- `account_id: str`
Account Identifier
- `direction: Optional[Literal["asc", "desc"]]`
The sorting direction.
- `"asc"`
- `"desc"`
- `is_recent: Optional[bool]`
- `is_similarity: Optional[bool]`
- `order: Optional[Literal["pattern", "created_at"]]`
The field to sort by.
- `"pattern"`
- `"created_at"`
- `page: Optional[int]`
The page number of paginated results.
- `pattern: Optional[str]`
- `per_page: Optional[int]`
The number of results per page.
- `search: Optional[str]`
Allows searching in multiple properties of a record simultaneously.
This parameter is intended for human users, not automation. Its exact
behavior is intentionally left unspecified and is subject to change
in the future.
### Returns
- `class TrustedDomainListResponse: …`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.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"
}
}
],
"result": [
{
"id": 2401,
"created_at": "2019-12-27T18:11:19.117Z",
"is_recent": true,
"is_regex": true,
"is_similarity": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"comments": "comments"
}
],
"result_info": {
"count": 1,
"page": 1,
"per_page": 20,
"total_count": 2000
},
"success": true
}
```
## Get a trusted email domain
`email_security.settings.trusted_domains.get(inttrusted_domain_id, TrustedDomainGetParams**kwargs) -> TrustedDomainGetResponse`
**get** `/accounts/{account_id}/email-security/settings/trusted_domains/{trusted_domain_id}`
Gets information about a specific trusted domain entry.
### Parameters
- `account_id: str`
Account Identifier
- `trusted_domain_id: int`
The unique identifier for the trusted domain.
### Returns
- `class TrustedDomainGetResponse: …`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
trusted_domain = client.email_security.settings.trusted_domains.get(
trusted_domain_id=2401,
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"
}
}
],
"result": {
"id": 2401,
"created_at": "2019-12-27T18:11:19.117Z",
"is_recent": true,
"is_regex": true,
"is_similarity": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"comments": "comments"
},
"success": true
}
```
## Create a trusted email domain
`email_security.settings.trusted_domains.create(TrustedDomainCreateParams**kwargs) -> TrustedDomainCreateResponse`
**post** `/accounts/{account_id}/email-security/settings/trusted_domains`
Adds a domain to the trusted domains list for email security, reducing false positive
detections.
### Parameters
- `account_id: str`
Account 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
- `TrustedDomainCreateResponse`
- `class EmailSecurityTrustedDomain: …`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
- `List[UnionMember1]`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
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)
```
#### 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": 2401,
"created_at": "2019-12-27T18:11:19.117Z",
"is_recent": true,
"is_regex": true,
"is_similarity": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"comments": "comments"
},
"success": true
}
```
## Update a trusted email domain
`email_security.settings.trusted_domains.edit(inttrusted_domain_id, TrustedDomainEditParams**kwargs) -> TrustedDomainEditResponse`
**patch** `/accounts/{account_id}/email-security/settings/trusted_domains/{trusted_domain_id}`
Modifies a trusted domain entry's configuration.
### Parameters
- `account_id: str`
Account Identifier
- `trusted_domain_id: int`
The unique identifier for the trusted domain.
- `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: …`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
response = client.email_security.settings.trusted_domains.edit(
trusted_domain_id=2401,
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"
}
}
],
"result": {
"id": 2401,
"created_at": "2019-12-27T18:11:19.117Z",
"is_recent": true,
"is_regex": true,
"is_similarity": true,
"last_modified": "2019-12-27T18:11:19.117Z",
"pattern": "x",
"comments": "comments"
},
"success": true
}
```
## Delete a trusted email domain
`email_security.settings.trusted_domains.delete(inttrusted_domain_id, TrustedDomainDeleteParams**kwargs) -> TrustedDomainDeleteResponse`
**delete** `/accounts/{account_id}/email-security/settings/trusted_domains/{trusted_domain_id}`
Removes a domain from the trusted domains list, subjecting it to normal security
scanning.
### Parameters
- `account_id: str`
Account Identifier
- `trusted_domain_id: int`
The unique identifier for the trusted domain.
### Returns
- `class TrustedDomainDeleteResponse: …`
- `id: int`
The unique identifier for the trusted domain.
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
trusted_domain = client.email_security.settings.trusted_domains.delete(
trusted_domain_id=2401,
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"
}
}
],
"result": {
"id": 2401
},
"success": true
}
```
## Domain Types
### Trusted Domain List Response
- `class TrustedDomainListResponse: …`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
### Trusted Domain Get Response
- `class TrustedDomainGetResponse: …`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
### Trusted Domain Create Response
- `TrustedDomainCreateResponse`
- `class EmailSecurityTrustedDomain: …`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
- `List[UnionMember1]`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
### Trusted Domain Edit Response
- `class TrustedDomainEditResponse: …`
- `id: int`
The unique identifier for the trusted domain.
- `created_at: datetime`
- `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.
- `last_modified: datetime`
- `pattern: str`
- `comments: Optional[str]`
### Trusted Domain Delete Response
- `class TrustedDomainDeleteResponse: …`
- `id: int`
The unique identifier for the trusted domain.
# Submissions
## Get reclassify submissions
`email_security.submissions.list(SubmissionListParams**kwargs) -> SyncV4PagePaginationArray[SubmissionListResponse]`
**get** `/accounts/{account_id}/email-security/submissions`
This endpoint returns information for submissions to made to reclassify emails.
### Parameters
- `account_id: str`
Account Identifier
- `customer_status: Optional[Literal["escalated", "reviewed", "unreviewed"]]`
- `"escalated"`
- `"reviewed"`
- `"unreviewed"`
- `end: Optional[Union[str, datetime]]`
The end of the search date range.
Defaults to `now` if not provided.
- `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]`
The page number of paginated results.
- `per_page: Optional[int]`
The number of results per page.
- `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` if not provided.
- `status: Optional[str]`
- `submission_id: Optional[str]`
- `type: Optional[Literal["TEAM", "USER"]]`
- `"TEAM"`
- `"USER"`
### Returns
- `class SubmissionListResponse: …`
- `requested_ts: datetime`
deprecated as of 2026-04-01, use `requested_at` instead.
- `submission_id: str`
- `customer_status: Optional[Literal["escalated", "reviewed", "unreviewed"]]`
- `"escalated"`
- `"reviewed"`
- `"unreviewed"`
- `escalated_as: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `escalated_at: Optional[datetime]`
- `escalated_by: Optional[str]`
- `escalated_submission_id: Optional[str]`
- `original_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `original_edf_hash: Optional[str]`
- `original_postfix_id: Optional[str]`
- `outcome: Optional[str]`
- `outcome_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `requested_at: Optional[datetime]`
- `requested_by: Optional[str]`
- `requested_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `status: Optional[str]`
- `subject: Optional[str]`
- `type: Optional[str]`
### Example
```python
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
page = client.email_security.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"
}
}
],
"result": [
{
"requested_ts": "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_at": "2019-12-27T18:11:19.117Z",
"requested_by": "requested_by",
"requested_disposition": "MALICIOUS",
"status": "status",
"subject": "subject",
"type": "type"
}
],
"result_info": {
"count": 1,
"page": 1,
"per_page": 20,
"total_count": 2000
},
"success": true
}
```
## Domain Types
### Submission List Response
- `class SubmissionListResponse: …`
- `requested_ts: datetime`
deprecated as of 2026-04-01, use `requested_at` instead.
- `submission_id: str`
- `customer_status: Optional[Literal["escalated", "reviewed", "unreviewed"]]`
- `"escalated"`
- `"reviewed"`
- `"unreviewed"`
- `escalated_as: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `escalated_at: Optional[datetime]`
- `escalated_by: Optional[str]`
- `escalated_submission_id: Optional[str]`
- `original_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `original_edf_hash: Optional[str]`
- `original_postfix_id: Optional[str]`
- `outcome: Optional[str]`
- `outcome_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `requested_at: Optional[datetime]`
- `requested_by: Optional[str]`
- `requested_disposition: Optional[Literal["MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", 7 more]]`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `status: Optional[str]`
- `subject: Optional[str]`
- `type: Optional[str]`