# Email Security
# Investigate
## Search email messages
**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.
### Path Parameters
- `account_id: string`
Account Identifier
### Query Parameters
- `action_log: optional boolean`
Determines if the message action log is included in the response.
- `alert_id: optional string`
- `cursor: optional string`
- `detections_only: optional boolean`
Determines if the search results will include detections or not.
- `domain: optional string`
Filter by a domain found in the email: sender domain, recipient domain, or a domain in a link.
- `end: optional string`
The end of the search date range.
Defaults to `now` if not provided.
- `exact_subject: optional string`
Search for messages with an exact subject match.
- `final_disposition: optional "MALICIOUS" or "SUSPICIOUS" or "SPOOF" or 3 more`
The dispositions the search filters by.
- `"MALICIOUS"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"NONE"`
- `message_action: optional "PREVIEW" or "QUARANTINE_RELEASED" or "MOVED" or "SUBMITTED"`
The message actions the search filters by.
- `"PREVIEW"`
- `"QUARANTINE_RELEASED"`
- `"MOVED"`
- `"SUBMITTED"`
- `message_id: optional string`
- `metric: optional string`
- `page: optional number`
Deprecated: Use cursor pagination instead.
- `per_page: optional number`
The number of results per page.
- `query: optional string`
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 string`
Filter by recipient. Matches either an email address or a domain.
- `sender: optional string`
Filter by sender. Matches either an email address or a domain.
- `start: optional string`
The beginning of the search date range.
Defaults to `now - 30 days` if not provided.
- `subject: optional string`
Search for messages containing individual keywords in any order within the subject.
- `submissions: optional boolean`
Search for submissions instead of original messages
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { id, action_log, client_recipients, 28 more }`
- `id: string`
- `action_log: unknown`
- `client_recipients: array of string`
- `detection_reasons: array of string`
- `is_phish_submission: boolean`
- `is_quarantined: boolean`
- `postfix_id: string`
The identifier of the message.
- `properties: object { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }`
- `allowlisted_pattern: optional string`
- `allowlisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `blocklisted_message: optional boolean`
- `blocklisted_pattern: optional string`
- `whitelisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `ts: string`
Deprecated, use `scanned_at` instead
- `alert_id: optional string`
- `delivery_mode: optional "DIRECT" or "BCC" or "JOURNAL" or 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 string`
- `envelope_from: optional string`
- `envelope_to: optional array of string`
- `final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `findings: optional array of object { attachment, detail, detection, 6 more }`
- `attachment: optional string`
- `detail: optional string`
- `detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `field: optional string`
- `name: optional string`
- `portion: optional string`
- `reason: optional string`
- `score: optional number`
- `value: optional string`
- `from: optional string`
- `from_name: optional string`
- `htmltext_structure_hash: optional string`
- `message_id: optional string`
- `post_delivery_operations: optional array of "PREVIEW" or "QUARANTINE_RELEASE" or "SUBMISSION" or "MOVE"`
- `"PREVIEW"`
- `"QUARANTINE_RELEASE"`
- `"SUBMISSION"`
- `"MOVE"`
- `postfix_id_outbound: optional string`
- `replyto: optional string`
- `scanned_at: optional string`
- `sent_at: optional string`
- `sent_date: optional string`
Deprecated, use `sent_at` instead
- `subject: optional string`
- `threat_categories: optional array of string`
- `to: optional array of string`
- `to_name: optional array of string`
- `validation: optional object { comment, dkim, dmarc, spf }`
- `comment: optional string`
- `dkim: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `result_info: object { count, page, per_page, 3 more }`
- `count: number`
- `page: number`
Deprecated: Returns always 0
- `per_page: number`
number of items per page
- `total_count: number`
Deprecated: Returns always 0
- `next: optional string`
- `previous: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**get** `/accounts/{account_id}/email-security/investigate/{postfix_id}`
Retrieves detailed information about a specific email message, including headers,
metadata, and security scan results.
### Path Parameters
- `account_id: string`
Account Identifier
- `postfix_id: string`
The identifier of the message.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, action_log, client_recipients, 28 more }`
- `id: string`
- `action_log: unknown`
- `client_recipients: array of string`
- `detection_reasons: array of string`
- `is_phish_submission: boolean`
- `is_quarantined: boolean`
- `postfix_id: string`
The identifier of the message.
- `properties: object { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }`
- `allowlisted_pattern: optional string`
- `allowlisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `blocklisted_message: optional boolean`
- `blocklisted_pattern: optional string`
- `whitelisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `ts: string`
Deprecated, use `scanned_at` instead
- `alert_id: optional string`
- `delivery_mode: optional "DIRECT" or "BCC" or "JOURNAL" or 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 string`
- `envelope_from: optional string`
- `envelope_to: optional array of string`
- `final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `findings: optional array of object { attachment, detail, detection, 6 more }`
- `attachment: optional string`
- `detail: optional string`
- `detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `field: optional string`
- `name: optional string`
- `portion: optional string`
- `reason: optional string`
- `score: optional number`
- `value: optional string`
- `from: optional string`
- `from_name: optional string`
- `htmltext_structure_hash: optional string`
- `message_id: optional string`
- `post_delivery_operations: optional array of "PREVIEW" or "QUARANTINE_RELEASE" or "SUBMISSION" or "MOVE"`
- `"PREVIEW"`
- `"QUARANTINE_RELEASE"`
- `"SUBMISSION"`
- `"MOVE"`
- `postfix_id_outbound: optional string`
- `replyto: optional string`
- `scanned_at: optional string`
- `sent_at: optional string`
- `sent_date: optional string`
Deprecated, use `sent_at` instead
- `subject: optional string`
- `threat_categories: optional array of string`
- `to: optional array of string`
- `to_name: optional array of string`
- `validation: optional object { comment, dkim, dmarc, spf }`
- `comment: optional string`
- `dkim: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/$POSTFIX_ID \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `InvestigateListResponse = object { id, action_log, client_recipients, 28 more }`
- `id: string`
- `action_log: unknown`
- `client_recipients: array of string`
- `detection_reasons: array of string`
- `is_phish_submission: boolean`
- `is_quarantined: boolean`
- `postfix_id: string`
The identifier of the message.
- `properties: object { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }`
- `allowlisted_pattern: optional string`
- `allowlisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `blocklisted_message: optional boolean`
- `blocklisted_pattern: optional string`
- `whitelisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `ts: string`
Deprecated, use `scanned_at` instead
- `alert_id: optional string`
- `delivery_mode: optional "DIRECT" or "BCC" or "JOURNAL" or 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 string`
- `envelope_from: optional string`
- `envelope_to: optional array of string`
- `final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `findings: optional array of object { attachment, detail, detection, 6 more }`
- `attachment: optional string`
- `detail: optional string`
- `detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `field: optional string`
- `name: optional string`
- `portion: optional string`
- `reason: optional string`
- `score: optional number`
- `value: optional string`
- `from: optional string`
- `from_name: optional string`
- `htmltext_structure_hash: optional string`
- `message_id: optional string`
- `post_delivery_operations: optional array of "PREVIEW" or "QUARANTINE_RELEASE" or "SUBMISSION" or "MOVE"`
- `"PREVIEW"`
- `"QUARANTINE_RELEASE"`
- `"SUBMISSION"`
- `"MOVE"`
- `postfix_id_outbound: optional string`
- `replyto: optional string`
- `scanned_at: optional string`
- `sent_at: optional string`
- `sent_date: optional string`
Deprecated, use `sent_at` instead
- `subject: optional string`
- `threat_categories: optional array of string`
- `to: optional array of string`
- `to_name: optional array of string`
- `validation: optional object { comment, dkim, dmarc, spf }`
- `comment: optional string`
- `dkim: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
### Investigate Get Response
- `InvestigateGetResponse = object { id, action_log, client_recipients, 28 more }`
- `id: string`
- `action_log: unknown`
- `client_recipients: array of string`
- `detection_reasons: array of string`
- `is_phish_submission: boolean`
- `is_quarantined: boolean`
- `postfix_id: string`
The identifier of the message.
- `properties: object { allowlisted_pattern, allowlisted_pattern_type, blocklisted_message, 2 more }`
- `allowlisted_pattern: optional string`
- `allowlisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `blocklisted_message: optional boolean`
- `blocklisted_pattern: optional string`
- `whitelisted_pattern_type: optional "quarantine_release" or "acceptable_sender" or "allowed_sender" or 5 more`
- `"quarantine_release"`
- `"acceptable_sender"`
- `"allowed_sender"`
- `"allowed_recipient"`
- `"domain_similarity"`
- `"domain_recency"`
- `"managed_acceptable_sender"`
- `"outbound_ndr"`
- `ts: string`
Deprecated, use `scanned_at` instead
- `alert_id: optional string`
- `delivery_mode: optional "DIRECT" or "BCC" or "JOURNAL" or 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 string`
- `envelope_from: optional string`
- `envelope_to: optional array of string`
- `final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `findings: optional array of object { attachment, detail, detection, 6 more }`
- `attachment: optional string`
- `detail: optional string`
- `detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `field: optional string`
- `name: optional string`
- `portion: optional string`
- `reason: optional string`
- `score: optional number`
- `value: optional string`
- `from: optional string`
- `from_name: optional string`
- `htmltext_structure_hash: optional string`
- `message_id: optional string`
- `post_delivery_operations: optional array of "PREVIEW" or "QUARANTINE_RELEASE" or "SUBMISSION" or "MOVE"`
- `"PREVIEW"`
- `"QUARANTINE_RELEASE"`
- `"SUBMISSION"`
- `"MOVE"`
- `postfix_id_outbound: optional string`
- `replyto: optional string`
- `scanned_at: optional string`
- `sent_at: optional string`
- `sent_date: optional string`
Deprecated, use `sent_at` instead
- `subject: optional string`
- `threat_categories: optional array of string`
- `to: optional array of string`
- `to_name: optional array of string`
- `validation: optional object { comment, dkim, dmarc, spf }`
- `comment: optional string`
- `dkim: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
# Detections
## Get message detection details
**get** `/accounts/{account_id}/email-security/investigate/{postfix_id}/detections`
Returns detection details such as threat categories and sender information for non-benign messages.
### Path Parameters
- `account_id: string`
Account Identifier
- `postfix_id: string`
The identifier of the message.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { action, attachments, headers, 5 more }`
- `action: string`
- `attachments: array of object { size, content_type, detection, 2 more }`
- `size: number`
- `content_type: optional string`
- `detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `encrypted: optional boolean`
- `name: optional string`
- `headers: array of object { name, value }`
- `name: string`
- `value: string`
- `links: array of object { href, text }`
- `href: string`
- `text: optional string`
- `sender_info: object { as_name, as_number, geo, 2 more }`
- `as_name: optional string`
The name of the autonomous system.
- `as_number: optional number`
The number of the autonomous system.
- `geo: optional string`
- `ip: optional string`
- `pld: optional string`
- `threat_categories: array of object { id, description, name }`
- `id: number`
- `description: optional string`
- `name: optional string`
- `validation: object { comment, dkim, dmarc, spf }`
- `comment: optional string`
- `dkim: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/$POSTFIX_ID/detections \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `DetectionGetResponse = object { action, attachments, headers, 5 more }`
- `action: string`
- `attachments: array of object { size, content_type, detection, 2 more }`
- `size: number`
- `content_type: optional string`
- `detection: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `encrypted: optional boolean`
- `name: optional string`
- `headers: array of object { name, value }`
- `name: string`
- `value: string`
- `links: array of object { href, text }`
- `href: string`
- `text: optional string`
- `sender_info: object { as_name, as_number, geo, 2 more }`
- `as_name: optional string`
The name of the autonomous system.
- `as_number: optional number`
The number of the autonomous system.
- `geo: optional string`
- `ip: optional string`
- `pld: optional string`
- `threat_categories: array of object { id, description, name }`
- `id: number`
- `description: optional string`
- `name: optional string`
- `validation: object { comment, dkim, dmarc, spf }`
- `comment: optional string`
- `dkim: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `dmarc: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `spf: optional "pass" or "neutral" or "fail" or 2 more`
- `"pass"`
- `"neutral"`
- `"fail"`
- `"error"`
- `"none"`
- `final_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
# Preview
## Get email preview
**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.
### Path Parameters
- `account_id: string`
Account Identifier
- `postfix_id: string`
The identifier of the message.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { screenshot }`
- `screenshot: string`
A base64 encoded PNG image of the email.
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/$POSTFIX_ID/preview \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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": "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAYAAADimHc4AAAAAXNSR0IArs4c6QAAAIRlWElmTU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAASgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAABgAAAAAQAAAGAAAAABAAOgAQADAAAAAQABAACgAgAEAAAAAQAAAGCgAwAEAAAAAQAAAGAAAAAAtVTeigAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAVlpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDYuMC4wIj4KICAgPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICAgICAgPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIKICAgICAgICAgICAgeG1sbnM6dGlmZj0iaHR0cDovL25zLmFkb2JlLmNvbS90aWZmLzEuMC8iPgogICAgICAgICA8dGlmZjpPcmllbnRhdGlvbj4xPC90aWZmOk9yaWVudGF0aW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KGV7hBwAACXtJREFUeAHtmwtwXFUZgP9zX7t3b7LNa9M2tGmLDbaWKpL6aBBJHdERQWGkU4u8CraVWmYQYWQUMSoKhZJikYo4Qqc6RVqkKmNHC0K1FGYoM9pqS4FAa9s0aTavfd3d+zq/527YSNvdzWY3m2ySc2c2595z/vOf///+e+4959wTAH5wApwAJ8AJcAKcACfACXACnAAnwAlwApwAJ8AJcAKcACfACXACnAAnwAlwApwAJ8AJcAKcACfACXACnAAnwAlwAhOJABmvzuCz158HXmUp2rCEOlhGbEdFh2qASFAgtiCKMUGgh8FM7IDDp3aQlt12Kfo6rgKAz3ylAQ3rJ/Fg39XYfyx32wUJpJpZ7wiq8LPebuGJaXfuipVKMHJ3YowsRgQC265aE+/quYf2/Le2YDM85aBOn/m7GDHX+m/4W0/B+gpUUNIBwN98rknvif4J+9urC/Tz7OqKBp66+vWSUf9dsvpx62yB0ckpyQDgLxtlS5iyyTx59OuATlFJkOrZYV9l7afItdv/XdSGMigvuQBEHmyqJRLug9DJ+gw2j3y2qIDWcOEPyFef/tHIK8+usaQCEGpdPFd0rEMQC8rZzS5OqXr+JU+JV2+5pjja02sV0mePfm7/I5+eIznm22MF3/U4/p+/L3d23LhxNL0viR7Qs/ETfo/lnIBIsHw0nU/bFiGgLbp0BfnirzanLR/hzJLoAV6QXywJ+C5cNu6N7d/7JD6zat4Is06rbswDENvU/A3sPd6Y1rqxyjRjkDj1zp7RaH5MA3CkpdkL0fAvRsPR4bbhBNtqcNvS7w233nDlxzQAgUp7E+pjPhnNyEw/duRefJLdJEU8pGLo7mptnuuTSJNHkeaBIPhMK/6Gbjm7A7ftfTPV3sGWBQpEu1ekrksxxWgQoLr6Tmbbj4tl34iOgmIbPnsLG8w9hKETajqDiX86sCXJe/1a4D4QEnfF2t/6fjq5UsojFTNQu21v0Z4UIxKA4LqL6nwyfQ3DJ8/JBR7x1wGIEmDfsVzEx1xGO3f+xeT6v7xcDEMKjmystXmRSkPtucJ3nWCy4wZ+0l7wfLsY8F2dBQWg46cfDaDVtw+MSLHsKwm98VDky8UypKAA+BVpF8T7i2Vb6eg1IiPyqE7nUN6joL51jUsw2nVBOqUTLc9TGfi965O++dLlomZvBSICyBoQpdyQVP8R4hFfgAQ+Spb8/PBwfc87AGWadrcR7x5ue+NS3qK2OxQFpcq72jGi7CXGvlGYYUAz7LGi7e6Shftba/x5ma1UB9ZDL2khlz1iuHWGOvJ+BJl65DNDKZ8I5UL17E515a4jri+OEbsoq096l2QeP3iXaR5N4MurH8SWliH5DimQqUHUezMVTah8tVx7wHUIdy6/gv3N7YlhRcHseOsOc9HBKL54S9Z1rrwCcLxlQdWEopzJGfbdGG7Y+XAyABK9MZNYxvx4t2r2vv067l55ayaZvAJgQ0zPpHAi5StT52xjnwfQ9cnWI9kfP5kcZ+8LM9i2EXfffE86kbwCMBuOmiCnXW1I18a4zCO+KuiVrZtSxqMVn5o6zyc1g+/+EF+47uYz6+Y8vg0/vPhygQjLRFH5JLXNWgx3+oGW5GazM33M61o+Z96VnpV//WOqsrF9SbInpK7zStnwVdDqmuQvbHk1VT9rAI63Lq6qJnQTNfRlkAin6kz4VKit/5ZvzZ7ksz/lrPmHy6KsF7CXQoGHp1JXOmoqUnuRMj6CEq0ff6Ay2tVDQ52TB77INmME6lecCd9FLlfUPFUg+oHqRp+Pzk08mtJ1Vg/oallQVlZR/i/a3/GBlNBkSIWqGW2iR7vCs3pX2tksvtQi2frBU1TvLnwEKChgls2ZWv75x7pOC4C7O8GbMNvYGD8wGaAD27QrT2s4KsrON6UVz+8cymd8fZUPYvLzZk9bEzjmUOJZy5VAw29J8+PXnRaAWGvjIQx3z89aM89CEmhwRMUXQVGRmOMC+x5AWOr+2NIKSwl7Ggoish8lRKDsSxplTVnuTwTU2aZzQwCMszehxXYu2AIhCQDKpvvERAImUGIK7jXSePJHWWpRHWw7wQYLcaDolplA0GLnukWddvmmpw+khpnDcQvfXF8DAlkKhnkhmEY52IYKlqGiZWho2z5KDYWtEPtpondGRr3eKlDKFsqDAQhvaLxfCHV/J2OFQgpkL2g152mw6rl4Pg4X0nSx6iL7PwQ4tF0GpXOAYchDIdIxMFIKHkRQKz2m8W4nWzcqz2SDUvfhS5KVO+9vXFhm9B5gd0gm2YLzhepze8G2goiCA6J7dxN31y0bxxKbBcUdz9psJ3ryjgc2d2Gb0m0KaDGTbHbHs/7Ozh1IUGC5wHoDEsthZQjUrWMTBMtheQSphQJYyFKB9Q6Kznup24Mck3Uvk1IITaP73iAtTFkeB+6/oxao8jHWA2ex3lVLEQPEtmqpZVewfxKpQjOmYLx/OpjR6mzqlfqFTyQDEHrogufESN/l2YQnXBmLuhyY+YpBjS/5177WM5R/+I9bA+Cl66ye0DUYbfcMJZ9LuVgz/wQJbrh4uho+wb4R5nUz5NJOact4/WznQ8VHylbuOZDJUNx97Vazu2P5SDMi5bNAKpetpfZkhe8SdyeYEfUVdlZ2ZgBwx5UVjoL7zWB7/ZllI3GNiW425vDVrBkJZeNaR/iUFnns4g+93wd89qpqC+Jtjh4uCvxkW1YMBDNhfvD9DU/Wc0VwBoff+FKz5JDwPrTNrC/Rglm5/zyIkVMF65kICmyHzRPeO5w+2Ow4dE7qumgpmwsIk2JXQw4E43H9n65Y75am8x2HfC2HKgWLEG+1I4BU1L2nBRs5GgrcLZM1t+9vd9vy+jx3j0abbhuypu0TSNnkWPbJBpWtV/w6VS6gsDR1XvQU6Vapa4qkJvrVaRTEMFvAsB2drcewQ/Q5BNj0JOSjA1NtljdFFwY/Srgzlwp1QNaVTx1inNU77dV12gU4qjSoI1XHictn5dla71l5KfnBdIjXl1U2oNcMKTh9SgfaPazthoHaXjswuBQ/8/ZX4ymdHVFHU+tmimoo4Ul4JBmdBFt5khDVBJtbS1junvt0REtO/tx6RLaSjIg+kKZ0oclktCibx//fP0HzCIIlCwnPFLn2+LHJsa8nBYSnnAAnwAlwApwAJ8AJcAKcACfACXACnAAnwAlwApwAJ8AJcAKcACfACXACnAAnwAlwApwAJ8AJcAKcACfACXACk4DA/wDoepVZ2hARhAAAAABJRU5ErkJggg=="
},
"success": true
}
```
## Preview for non-detection messages
**post** `/accounts/{account_id}/email-security/investigate/preview`
Generates a preview of an email message for safe viewing without executing any
embedded content.
### Path Parameters
- `account_id: string`
Account Identifier
### Body Parameters
- `postfix_id: string`
The identifier of the message.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { screenshot }`
- `screenshot: string`
A base64 encoded PNG image of the email.
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/preview \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{
"postfix_id": "4Njp3P0STMz2c02Q"
}'
```
#### 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": "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAYAAADimHc4AAAAAXNSR0IArs4c6QAAAIRlWElmTU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAASgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAABgAAAAAQAAAGAAAAABAAOgAQADAAAAAQABAACgAgAEAAAAAQAAAGCgAwAEAAAAAQAAAGAAAAAAtVTeigAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAVlpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDYuMC4wIj4KICAgPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICAgICAgPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIKICAgICAgICAgICAgeG1sbnM6dGlmZj0iaHR0cDovL25zLmFkb2JlLmNvbS90aWZmLzEuMC8iPgogICAgICAgICA8dGlmZjpPcmllbnRhdGlvbj4xPC90aWZmOk9yaWVudGF0aW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KGV7hBwAACXtJREFUeAHtmwtwXFUZgP9zX7t3b7LNa9M2tGmLDbaWKpL6aBBJHdERQWGkU4u8CraVWmYQYWQUMSoKhZJikYo4Qqc6RVqkKmNHC0K1FGYoM9pqS4FAa9s0aTavfd3d+zq/527YSNvdzWY3m2ySc2c2595z/vOf///+e+4959wTAH5wApwAJ8AJcAKcACfACXACnAAnwAlwApwAJ8AJcAKcACfACXACnAAnwAlwApwAJ8AJcAKcACfACXACnAAnwAlwAhOJABmvzuCz158HXmUp2rCEOlhGbEdFh2qASFAgtiCKMUGgh8FM7IDDp3aQlt12Kfo6rgKAz3ylAQ3rJ/Fg39XYfyx32wUJpJpZ7wiq8LPebuGJaXfuipVKMHJ3YowsRgQC265aE+/quYf2/Le2YDM85aBOn/m7GDHX+m/4W0/B+gpUUNIBwN98rknvif4J+9urC/Tz7OqKBp66+vWSUf9dsvpx62yB0ckpyQDgLxtlS5iyyTx59OuATlFJkOrZYV9l7afItdv/XdSGMigvuQBEHmyqJRLug9DJ+gw2j3y2qIDWcOEPyFef/tHIK8+usaQCEGpdPFd0rEMQC8rZzS5OqXr+JU+JV2+5pjja02sV0mePfm7/I5+eIznm22MF3/U4/p+/L3d23LhxNL0viR7Qs/ETfo/lnIBIsHw0nU/bFiGgLbp0BfnirzanLR/hzJLoAV6QXywJ+C5cNu6N7d/7JD6zat4Is06rbswDENvU/A3sPd6Y1rqxyjRjkDj1zp7RaH5MA3CkpdkL0fAvRsPR4bbhBNtqcNvS7w233nDlxzQAgUp7E+pjPhnNyEw/duRefJLdJEU8pGLo7mptnuuTSJNHkeaBIPhMK/6Gbjm7A7ftfTPV3sGWBQpEu1ekrksxxWgQoLr6Tmbbj4tl34iOgmIbPnsLG8w9hKETajqDiX86sCXJe/1a4D4QEnfF2t/6fjq5UsojFTNQu21v0Z4UIxKA4LqL6nwyfQ3DJ8/JBR7x1wGIEmDfsVzEx1xGO3f+xeT6v7xcDEMKjmystXmRSkPtucJ3nWCy4wZ+0l7wfLsY8F2dBQWg46cfDaDVtw+MSLHsKwm98VDky8UypKAA+BVpF8T7i2Vb6eg1IiPyqE7nUN6joL51jUsw2nVBOqUTLc9TGfi965O++dLlomZvBSICyBoQpdyQVP8R4hFfgAQ+Spb8/PBwfc87AGWadrcR7x5ue+NS3qK2OxQFpcq72jGi7CXGvlGYYUAz7LGi7e6Shftba/x5ma1UB9ZDL2khlz1iuHWGOvJ+BJl65DNDKZ8I5UL17E515a4jri+OEbsoq096l2QeP3iXaR5N4MurH8SWliH5DimQqUHUezMVTah8tVx7wHUIdy6/gv3N7YlhRcHseOsOc9HBKL54S9Z1rrwCcLxlQdWEopzJGfbdGG7Y+XAyABK9MZNYxvx4t2r2vv067l55ayaZvAJgQ0zPpHAi5StT52xjnwfQ9cnWI9kfP5kcZ+8LM9i2EXfffE86kbwCMBuOmiCnXW1I18a4zCO+KuiVrZtSxqMVn5o6zyc1g+/+EF+47uYz6+Y8vg0/vPhygQjLRFH5JLXNWgx3+oGW5GazM33M61o+Z96VnpV//WOqsrF9SbInpK7zStnwVdDqmuQvbHk1VT9rAI63Lq6qJnQTNfRlkAin6kz4VKit/5ZvzZ7ksz/lrPmHy6KsF7CXQoGHp1JXOmoqUnuRMj6CEq0ff6Ay2tVDQ52TB77INmME6lecCd9FLlfUPFUg+oHqRp+Pzk08mtJ1Vg/oallQVlZR/i/a3/GBlNBkSIWqGW2iR7vCs3pX2tksvtQi2frBU1TvLnwEKChgls2ZWv75x7pOC4C7O8GbMNvYGD8wGaAD27QrT2s4KsrON6UVz+8cymd8fZUPYvLzZk9bEzjmUOJZy5VAw29J8+PXnRaAWGvjIQx3z89aM89CEmhwRMUXQVGRmOMC+x5AWOr+2NIKSwl7Ggoish8lRKDsSxplTVnuTwTU2aZzQwCMszehxXYu2AIhCQDKpvvERAImUGIK7jXSePJHWWpRHWw7wQYLcaDolplA0GLnukWddvmmpw+khpnDcQvfXF8DAlkKhnkhmEY52IYKlqGiZWho2z5KDYWtEPtpondGRr3eKlDKFsqDAQhvaLxfCHV/J2OFQgpkL2g152mw6rl4Pg4X0nSx6iL7PwQ4tF0GpXOAYchDIdIxMFIKHkRQKz2m8W4nWzcqz2SDUvfhS5KVO+9vXFhm9B5gd0gm2YLzhepze8G2goiCA6J7dxN31y0bxxKbBcUdz9psJ3ryjgc2d2Gb0m0KaDGTbHbHs/7Ozh1IUGC5wHoDEsthZQjUrWMTBMtheQSphQJYyFKB9Q6Kznup24Mck3Uvk1IITaP73iAtTFkeB+6/oxao8jHWA2ex3lVLEQPEtmqpZVewfxKpQjOmYLx/OpjR6mzqlfqFTyQDEHrogufESN/l2YQnXBmLuhyY+YpBjS/5177WM5R/+I9bA+Cl66ye0DUYbfcMJZ9LuVgz/wQJbrh4uho+wb4R5nUz5NJOact4/WznQ8VHylbuOZDJUNx97Vazu2P5SDMi5bNAKpetpfZkhe8SdyeYEfUVdlZ2ZgBwx5UVjoL7zWB7/ZllI3GNiW425vDVrBkJZeNaR/iUFnns4g+93wd89qpqC+Jtjh4uCvxkW1YMBDNhfvD9DU/Wc0VwBoff+FKz5JDwPrTNrC/Rglm5/zyIkVMF65kICmyHzRPeO5w+2Ow4dE7qumgpmwsIk2JXQw4E43H9n65Y75am8x2HfC2HKgWLEG+1I4BU1L2nBRs5GgrcLZM1t+9vd9vy+jx3j0abbhuypu0TSNnkWPbJBpWtV/w6VS6gsDR1XvQU6Vapa4qkJvrVaRTEMFvAsB2drcewQ/Q5BNj0JOSjA1NtljdFFwY/Srgzlwp1QNaVTx1inNU77dV12gU4qjSoI1XHictn5dla71l5KfnBdIjXl1U2oNcMKTh9SgfaPazthoHaXjswuBQ/8/ZX4ymdHVFHU+tmimoo4Ul4JBmdBFt5khDVBJtbS1junvt0REtO/tx6RLaSjIg+kKZ0oclktCibx//fP0HzCIIlCwnPFLn2+LHJsa8nBYSnnAAnwAlwApwAJ8AJcAKcACfACXACnAAnwAlwApwAJ8AJcAKcACfACXACnAAnwAlwApwAJ8AJcAKcACfACXACk4DA/wDoepVZ2hARhAAAAABJRU5ErkJggg=="
},
"success": true
}
```
## Domain Types
### Preview Get Response
- `PreviewGetResponse = object { screenshot }`
- `screenshot: string`
A base64 encoded PNG image of the email.
### Preview Create Response
- `PreviewCreateResponse = object { screenshot }`
- `screenshot: string`
A base64 encoded PNG image of the email.
# Raw
## Get raw email content
**get** `/accounts/{account_id}/email-security/investigate/{postfix_id}/raw`
Returns the raw eml of any non-benign message.
### Path Parameters
- `account_id: string`
Account Identifier
- `postfix_id: string`
The identifier of the message.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { raw }`
- `raw: string`
A UTF-8 encoded eml file of the email.
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/$POSTFIX_ID/raw \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `RawGetResponse = object { raw }`
- `raw: string`
A UTF-8 encoded eml file of the email.
# Trace
## Get email trace
**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.
### Path Parameters
- `account_id: string`
Account Identifier
- `postfix_id: string`
The identifier of the message.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { inbound, outbound }`
- `inbound: object { lines, pending }`
- `lines: optional array of object { lineno, message, ts }`
- `lineno: number`
- `message: string`
- `ts: string`
- `pending: optional boolean`
- `outbound: object { lines, pending }`
- `lines: optional array of object { lineno, message, ts }`
- `lineno: number`
- `message: string`
- `ts: string`
- `pending: optional boolean`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/$POSTFIX_ID/trace \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `TraceGetResponse = object { inbound, outbound }`
- `inbound: object { lines, pending }`
- `lines: optional array of object { lineno, message, ts }`
- `lineno: number`
- `message: string`
- `ts: string`
- `pending: optional boolean`
- `outbound: object { lines, pending }`
- `lines: optional array of object { lineno, message, ts }`
- `lineno: number`
- `message: string`
- `ts: string`
- `pending: optional boolean`
# Move
## Move a message
**post** `/accounts/{account_id}/email-security/investigate/{postfix_id}/move`
Moves a single email message to a different folder or changes its quarantine status.
### Path Parameters
- `account_id: string`
Account Identifier
- `postfix_id: string`
The identifier of the message.
### Body Parameters
- `destination: "Inbox" or "JunkEmail" or "DeletedItems" or 2 more`
- `"Inbox"`
- `"JunkEmail"`
- `"DeletedItems"`
- `"RecoverableItemsDeletions"`
- `"RecoverableItemsPurges"`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { completed_timestamp, item_count, success, 6 more }`
- `completed_timestamp: string`
Deprecated, use `completed_at` instead
- `item_count: number`
- `success: boolean`
- `completed_at: optional string`
- `destination: optional string`
- `message_id: optional string`
- `operation: optional string`
- `recipient: optional string`
- `status: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/$POSTFIX_ID/move \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{
"destination": "Inbox"
}'
```
#### 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
**post** `/accounts/{account_id}/email-security/investigate/move`
Maximum batch size: 1000 messages per request
### Path Parameters
- `account_id: string`
Account Identifier
### Body Parameters
- `destination: "Inbox" or "JunkEmail" or "DeletedItems" or 2 more`
- `"Inbox"`
- `"JunkEmail"`
- `"DeletedItems"`
- `"RecoverableItemsDeletions"`
- `"RecoverableItemsPurges"`
- `ids: optional array of string`
List of message IDs to move.
- `postfix_ids: optional array of string`
Deprecated: Use `ids` instead. List of message IDs to move.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { completed_timestamp, item_count, success, 6 more }`
- `completed_timestamp: string`
Deprecated, use `completed_at` instead
- `item_count: number`
- `success: boolean`
- `completed_at: optional string`
- `destination: optional string`
- `message_id: optional string`
- `operation: optional string`
- `recipient: optional string`
- `status: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/move \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{
"destination": "Inbox"
}'
```
#### 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
- `MoveCreateResponse = object { completed_timestamp, item_count, success, 6 more }`
- `completed_timestamp: string`
Deprecated, use `completed_at` instead
- `item_count: number`
- `success: boolean`
- `completed_at: optional string`
- `destination: optional string`
- `message_id: optional string`
- `operation: optional string`
- `recipient: optional string`
- `status: optional string`
### Move Bulk Response
- `MoveBulkResponse = object { completed_timestamp, item_count, success, 6 more }`
- `completed_timestamp: string`
Deprecated, use `completed_at` instead
- `item_count: number`
- `success: boolean`
- `completed_at: optional string`
- `destination: optional string`
- `message_id: optional string`
- `operation: optional string`
- `recipient: optional string`
- `status: optional string`
# Reclassify
## Change email classification
**post** `/accounts/{account_id}/email-security/investigate/{postfix_id}/reclassify`
Submits an email message for reclassification, updating its threat assessment
based on new analysis.
### Path Parameters
- `account_id: string`
Account Identifier
- `postfix_id: string`
The identifier of the message.
### Body Parameters
- `expected_disposition: "NONE" or "BULK" or "MALICIOUS" or 3 more`
- `"NONE"`
- `"BULK"`
- `"MALICIOUS"`
- `"SPAM"`
- `"SPOOF"`
- `"SUSPICIOUS"`
- `eml_content: optional string`
Base64 encoded content of the EML file
- `escalated_submission_id: optional string`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: unknown`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/$POSTFIX_ID/reclassify \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{
"expected_disposition": "NONE"
}'
```
#### 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
}
```
## Domain Types
### Reclassify Create Response
- `ReclassifyCreateResponse = unknown`
# Release
## Release messages from quarantine
**post** `/accounts/{account_id}/email-security/investigate/release`
Releases a quarantined email message, allowing it to be delivered to the recipient.
### Path Parameters
- `account_id: string`
Account Identifier
### Body Parameters
- `body: array of string`
A list of messages identfied by their `postfix_id`s that should be released.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { id, postfix_id, delivered, 2 more }`
- `id: string`
- `postfix_id: string`
The identifier of the message.
- `delivered: optional array of string`
- `failed: optional array of string`
- `undelivered: optional array of string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/investigate/release \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '[
"4Njp3P0STMz2c02Q"
]'
```
#### 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
- `ReleaseBulkResponse = object { id, postfix_id, delivered, 2 more }`
- `id: string`
- `postfix_id: string`
The identifier of the message.
- `delivered: optional array of string`
- `failed: optional array of string`
- `undelivered: optional array of string`
# Phishguard
# Reports
## Get `PhishGuard` reports
**get** `/accounts/{account_id}/email-security/phishguard/reports`
Retrieves `PhishGuard` reports showing phishing attempts and suspicious email patterns
detected.
### Path Parameters
- `account_id: string`
Account Identifier
### Query Parameters
- `end: optional string`
The end of the search date range (RFC3339 format).
- `from_date: optional string`
- `start: optional string`
The beginning of the search date range (RFC3339 format).
- `to_date: optional string`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { id, content, created_at, 7 more }`
- `id: number`
- `content: string`
- `created_at: string`
- `disposition: "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `fields: object { to, ts, from, postfix_id }`
- `to: array of string`
- `ts: string`
- `from: optional string`
- `postfix_id: optional string`
- `priority: string`
- `title: string`
- `ts: string`
- `updated_at: string`
- `tags: optional array of object { category, value }`
- `category: string`
- `value: string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/phishguard/reports \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `ReportListResponse = object { id, content, created_at, 7 more }`
- `id: number`
- `content: string`
- `created_at: string`
- `disposition: "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `fields: object { to, ts, from, postfix_id }`
- `to: array of string`
- `ts: string`
- `from: optional string`
- `postfix_id: optional string`
- `priority: string`
- `title: string`
- `ts: string`
- `updated_at: string`
- `tags: optional array of object { category, value }`
- `category: string`
- `value: string`
# Settings
# Allow Policies
## List email allow policies
**get** `/accounts/{account_id}/email-security/settings/allow_policies`
Lists, searches, and sorts an account’s email allow policies.
### Path Parameters
- `account_id: string`
Account Identifier
### Query Parameters
- `direction: optional "asc" or "desc"`
The sorting direction.
- `"asc"`
- `"desc"`
- `is_acceptable_sender: optional boolean`
- `is_exempt_recipient: optional boolean`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
- `is_trusted_sender: optional boolean`
- `order: optional "pattern" or "created_at"`
The field to sort by.
- `"pattern"`
- `"created_at"`
- `page: optional number`
The page number of paginated results.
- `pattern: optional string`
- `pattern_type: optional "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `per_page: optional number`
The number of results per page.
- `search: optional string`
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 boolean`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { id, created_at, is_acceptable_sender, 11 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_acceptable_sender: boolean`
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: boolean`
Messages to this recipient will bypass all detections.
- `is_regex: boolean`
- `is_trusted_sender: boolean`
Messages from this sender will bypass all detections and link following.
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
- `comments: optional string`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
- `result_info: object { count, page, per_page, total_count }`
- `count: number`
Total number of results for the requested service
- `page: number`
Current page within paginated list of results
- `per_page: number`
Number of results per page of results
- `total_count: number`
Total results available without any search parameters
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/allow_policies \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**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.
### Path Parameters
- `account_id: string`
Account Identifier
- `policy_id: number`
The unique identifier for the allow policy.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, is_acceptable_sender, 11 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_acceptable_sender: boolean`
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: boolean`
Messages to this recipient will bypass all detections.
- `is_regex: boolean`
- `is_trusted_sender: boolean`
Messages from this sender will bypass all detections and link following.
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
- `comments: optional string`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/allow_policies/$POLICY_ID \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**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.
### Path Parameters
- `account_id: string`
Account Identifier
### Body Parameters
- `is_acceptable_sender: boolean`
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: boolean`
Messages to this recipient will bypass all detections.
- `is_regex: boolean`
- `is_trusted_sender: boolean`
Messages from this sender will bypass all detections and link following.
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
- `comments: optional string`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, is_acceptable_sender, 11 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_acceptable_sender: boolean`
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: boolean`
Messages to this recipient will bypass all detections.
- `is_regex: boolean`
- `is_trusted_sender: boolean`
Messages from this sender will bypass all detections and link following.
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
- `comments: optional string`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/allow_policies \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{
"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
}'
```
#### 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
**patch** `/accounts/{account_id}/email-security/settings/allow_policies/{policy_id}`
Updates an existing email allow policy, modifying its matching criteria or scope.
### Path Parameters
- `account_id: string`
Account Identifier
- `policy_id: number`
The unique identifier for the allow policy.
### Body Parameters
- `comments: optional string`
- `is_acceptable_sender: optional boolean`
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 boolean`
Messages to this recipient will bypass all detections.
- `is_regex: optional boolean`
- `is_trusted_sender: optional boolean`
Messages from this sender will bypass all detections and link following.
- `pattern: optional string`
- `pattern_type: optional "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: optional boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, is_acceptable_sender, 11 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_acceptable_sender: boolean`
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: boolean`
Messages to this recipient will bypass all detections.
- `is_regex: boolean`
- `is_trusted_sender: boolean`
Messages from this sender will bypass all detections and link following.
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
- `comments: optional string`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/allow_policies/$POLICY_ID \
-X PATCH \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{}'
```
#### 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
**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.
### Path Parameters
- `account_id: string`
Account Identifier
- `policy_id: number`
The unique identifier for the allow policy.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id }`
- `id: number`
The unique identifier for the allow policy.
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/allow_policies/$POLICY_ID \
-X DELETE \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `AllowPolicyListResponse = object { id, created_at, is_acceptable_sender, 11 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_acceptable_sender: boolean`
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: boolean`
Messages to this recipient will bypass all detections.
- `is_regex: boolean`
- `is_trusted_sender: boolean`
Messages from this sender will bypass all detections and link following.
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
- `comments: optional string`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
### Allow Policy Get Response
- `AllowPolicyGetResponse = object { id, created_at, is_acceptable_sender, 11 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_acceptable_sender: boolean`
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: boolean`
Messages to this recipient will bypass all detections.
- `is_regex: boolean`
- `is_trusted_sender: boolean`
Messages from this sender will bypass all detections and link following.
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
- `comments: optional string`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
### Allow Policy Create Response
- `AllowPolicyCreateResponse = object { id, created_at, is_acceptable_sender, 11 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_acceptable_sender: boolean`
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: boolean`
Messages to this recipient will bypass all detections.
- `is_regex: boolean`
- `is_trusted_sender: boolean`
Messages from this sender will bypass all detections and link following.
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
- `comments: optional string`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
### Allow Policy Edit Response
- `AllowPolicyEditResponse = object { id, created_at, is_acceptable_sender, 11 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_acceptable_sender: boolean`
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: boolean`
Messages to this recipient will bypass all detections.
- `is_regex: boolean`
- `is_trusted_sender: boolean`
Messages from this sender will bypass all detections and link following.
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `verify_sender: boolean`
Enforce DMARC, SPF or DKIM authentication.
When on, Email Security only honors policies that pass authentication.
- `comments: optional string`
- `is_recipient: optional boolean`
- `is_sender: optional boolean`
- `is_spoof: optional boolean`
### Allow Policy Delete Response
- `AllowPolicyDeleteResponse = object { id }`
- `id: number`
The unique identifier for the allow policy.
# Block Senders
## List blocked email senders
**get** `/accounts/{account_id}/email-security/settings/block_senders`
Lists all blocked sender entries with their patterns and block reasons.
### Path Parameters
- `account_id: string`
Account Identifier
### Query Parameters
- `direction: optional "asc" or "desc"`
The sorting direction.
- `"asc"`
- `"desc"`
- `order: optional "pattern" or "created_at"`
The field to sort by.
- `"pattern"`
- `"created_at"`
- `page: optional number`
The page number of paginated results.
- `pattern: optional string`
- `pattern_type: optional "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `per_page: optional number`
The number of results per page.
- `search: optional string`
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
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { id, created_at, is_regex, 4 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_regex: boolean`
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: optional string`
- `result_info: object { count, page, per_page, total_count }`
- `count: number`
Total number of results for the requested service
- `page: number`
Current page within paginated list of results
- `per_page: number`
Number of results per page of results
- `total_count: number`
Total results available without any search parameters
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/block_senders \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**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.
### Path Parameters
- `account_id: string`
Account Identifier
- `pattern_id: number`
The unique identifier for the allow policy.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, is_regex, 4 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_regex: boolean`
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/block_senders/$PATTERN_ID \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**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.
### Path Parameters
- `account_id: string`
Account Identifier
### Body Parameters
- `is_regex: boolean`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: optional string`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, is_regex, 4 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_regex: boolean`
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/block_senders \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{
"is_regex": false,
"pattern": "test@example.com",
"pattern_type": "EMAIL"
}'
```
#### 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
**patch** `/accounts/{account_id}/email-security/settings/block_senders/{pattern_id}`
Modifies a blocked sender entry, updating its pattern or block reason.
### Path Parameters
- `account_id: string`
Account Identifier
- `pattern_id: number`
The unique identifier for the allow policy.
### Body Parameters
- `comments: optional string`
- `is_regex: optional boolean`
- `pattern: optional string`
- `pattern_type: optional "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, is_regex, 4 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_regex: boolean`
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/block_senders/$PATTERN_ID \
-X PATCH \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{}'
```
#### 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
**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.
### Path Parameters
- `account_id: string`
Account Identifier
- `pattern_id: number`
The unique identifier for the allow policy.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id }`
- `id: number`
The unique identifier for the allow policy.
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/block_senders/$PATTERN_ID \
-X DELETE \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `BlockSenderListResponse = object { id, created_at, is_regex, 4 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_regex: boolean`
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: optional string`
### Block Sender Get Response
- `BlockSenderGetResponse = object { id, created_at, is_regex, 4 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_regex: boolean`
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: optional string`
### Block Sender Create Response
- `BlockSenderCreateResponse = object { id, created_at, is_regex, 4 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_regex: boolean`
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: optional string`
### Block Sender Edit Response
- `BlockSenderEditResponse = object { id, created_at, is_regex, 4 more }`
- `id: number`
The unique identifier for the allow policy.
- `created_at: string`
- `is_regex: boolean`
- `last_modified: string`
- `pattern: string`
- `pattern_type: "EMAIL" or "DOMAIN" or "IP" or "UNKNOWN"`
- `"EMAIL"`
- `"DOMAIN"`
- `"IP"`
- `"UNKNOWN"`
- `comments: optional string`
### Block Sender Delete Response
- `BlockSenderDeleteResponse = object { id }`
- `id: number`
The unique identifier for the allow policy.
# Domains
## List protected email domains
**get** `/accounts/{account_id}/email-security/settings/domains`
Lists, searches, and sorts an account’s email domains.
### Path Parameters
- `account_id: string`
Account Identifier
### Query Parameters
- `active_delivery_mode: optional "DIRECT" or "BCC" or "JOURNAL" or 2 more`
Filters response to domains with the currently active delivery mode.
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `allowed_delivery_mode: optional "DIRECT" or "BCC" or "JOURNAL" or 2 more`
Filters response to domains with the provided delivery mode.
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `direction: optional "asc" or "desc"`
The sorting direction.
- `"asc"`
- `"desc"`
- `domain: optional array of string`
Filters results by the provided domains, allowing for multiple occurrences.
- `integration_id: optional string`
Filters response to domains with the provided integration ID.
- `order: optional "domain" or "created_at"`
The field to sort by.
- `"domain"`
- `"created_at"`
- `page: optional number`
The page number of paginated results.
- `per_page: optional number`
The number of results per page.
- `search: optional string`
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
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { id, allowed_delivery_modes, created_at, 17 more }`
- `id: number`
The unique identifier for the domain.
- `allowed_delivery_modes: array of "DIRECT" or "BCC" or "JOURNAL" or 2 more`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: string`
- `domain: string`
- `drop_dispositions: array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: array of string`
- `last_modified: string`
- `lookback_hops: number`
- `regions: array of "GLOBAL" or "AU" or "DE" or 2 more`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: string`
- `authorization: optional object { authorized, timestamp, status_message }`
- `authorized: boolean`
- `timestamp: string`
- `status_message: optional string`
- `dmarc_status: optional "none" or "good" or "invalid"`
- `"none"`
- `"good"`
- `"invalid"`
- `emails_processed: optional object { timestamp, total_emails_processed, total_emails_processed_previous }`
- `timestamp: string`
- `total_emails_processed: number`
- `total_emails_processed_previous: number`
- `folder: optional "AllItems" or "Inbox"`
- `"AllItems"`
- `"Inbox"`
- `inbox_provider: optional "Microsoft" or "Google"`
- `"Microsoft"`
- `"Google"`
- `integration_id: optional string`
- `o365_tenant_id: optional string`
- `require_tls_inbound: optional boolean`
- `require_tls_outbound: optional boolean`
- `spf_status: optional "none" or "good" or "neutral" or 2 more`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
- `result_info: object { count, page, per_page, total_count }`
- `count: number`
Total number of results for the requested service
- `page: number`
Current page within paginated list of results
- `per_page: number`
Number of results per page of results
- `total_count: number`
Total results available without any search parameters
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/domains \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**get** `/accounts/{account_id}/email-security/settings/domains/{domain_id}`
Gets configuration details for a specific domain in email security.
### Path Parameters
- `account_id: string`
Account Identifier
- `domain_id: number`
The unique identifier for the domain.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, allowed_delivery_modes, created_at, 17 more }`
- `id: number`
The unique identifier for the domain.
- `allowed_delivery_modes: array of "DIRECT" or "BCC" or "JOURNAL" or 2 more`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: string`
- `domain: string`
- `drop_dispositions: array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: array of string`
- `last_modified: string`
- `lookback_hops: number`
- `regions: array of "GLOBAL" or "AU" or "DE" or 2 more`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: string`
- `authorization: optional object { authorized, timestamp, status_message }`
- `authorized: boolean`
- `timestamp: string`
- `status_message: optional string`
- `dmarc_status: optional "none" or "good" or "invalid"`
- `"none"`
- `"good"`
- `"invalid"`
- `emails_processed: optional object { timestamp, total_emails_processed, total_emails_processed_previous }`
- `timestamp: string`
- `total_emails_processed: number`
- `total_emails_processed_previous: number`
- `folder: optional "AllItems" or "Inbox"`
- `"AllItems"`
- `"Inbox"`
- `inbox_provider: optional "Microsoft" or "Google"`
- `"Microsoft"`
- `"Google"`
- `integration_id: optional string`
- `o365_tenant_id: optional string`
- `require_tls_inbound: optional boolean`
- `require_tls_outbound: optional boolean`
- `spf_status: optional "none" or "good" or "neutral" or 2 more`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/domains/$DOMAIN_ID \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**patch** `/accounts/{account_id}/email-security/settings/domains/{domain_id}`
Updates configuration for a domain in email security.
### Path Parameters
- `account_id: string`
Account Identifier
- `domain_id: number`
The unique identifier for the domain.
### Body Parameters
- `ip_restrictions: array of string`
- `allowed_delivery_modes: optional array of "DIRECT" or "BCC" or "JOURNAL" or 2 more`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `domain: optional string`
- `drop_dispositions: optional array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `folder: optional "AllItems" or "Inbox"`
- `"AllItems"`
- `"Inbox"`
- `integration_id: optional string`
- `lookback_hops: optional number`
- `regions: optional array of "GLOBAL" or "AU" or "DE" or 2 more`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `require_tls_inbound: optional boolean`
- `require_tls_outbound: optional boolean`
- `transport: optional string`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, allowed_delivery_modes, created_at, 17 more }`
- `id: number`
The unique identifier for the domain.
- `allowed_delivery_modes: array of "DIRECT" or "BCC" or "JOURNAL" or 2 more`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: string`
- `domain: string`
- `drop_dispositions: array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: array of string`
- `last_modified: string`
- `lookback_hops: number`
- `regions: array of "GLOBAL" or "AU" or "DE" or 2 more`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: string`
- `authorization: optional object { authorized, timestamp, status_message }`
- `authorized: boolean`
- `timestamp: string`
- `status_message: optional string`
- `dmarc_status: optional "none" or "good" or "invalid"`
- `"none"`
- `"good"`
- `"invalid"`
- `emails_processed: optional object { timestamp, total_emails_processed, total_emails_processed_previous }`
- `timestamp: string`
- `total_emails_processed: number`
- `total_emails_processed_previous: number`
- `folder: optional "AllItems" or "Inbox"`
- `"AllItems"`
- `"Inbox"`
- `inbox_provider: optional "Microsoft" or "Google"`
- `"Microsoft"`
- `"Google"`
- `integration_id: optional string`
- `o365_tenant_id: optional string`
- `require_tls_inbound: optional boolean`
- `require_tls_outbound: optional boolean`
- `spf_status: optional "none" or "good" or "neutral" or 2 more`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/domains/$DOMAIN_ID \
-X PATCH \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{
"ip_restrictions": [
"192.0.2.0/24",
"2001:db8::/32"
]
}'
```
#### 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
**delete** `/accounts/{account_id}/email-security/settings/domains/{domain_id}`
Unprotect an email domain
### Path Parameters
- `account_id: string`
Account Identifier
- `domain_id: number`
The unique identifier for the domain.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id }`
- `id: number`
The unique identifier for the domain.
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/domains/$DOMAIN_ID \
-X DELETE \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**delete** `/accounts/{account_id}/email-security/settings/domains`
Bulk removes multiple domains from email security configuration in a single request.
### Path Parameters
- `account_id: string`
Account Identifier
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { id }`
- `id: number`
The unique identifier for the domain.
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/domains \
-X DELETE \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `DomainListResponse = object { id, allowed_delivery_modes, created_at, 17 more }`
- `id: number`
The unique identifier for the domain.
- `allowed_delivery_modes: array of "DIRECT" or "BCC" or "JOURNAL" or 2 more`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: string`
- `domain: string`
- `drop_dispositions: array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: array of string`
- `last_modified: string`
- `lookback_hops: number`
- `regions: array of "GLOBAL" or "AU" or "DE" or 2 more`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: string`
- `authorization: optional object { authorized, timestamp, status_message }`
- `authorized: boolean`
- `timestamp: string`
- `status_message: optional string`
- `dmarc_status: optional "none" or "good" or "invalid"`
- `"none"`
- `"good"`
- `"invalid"`
- `emails_processed: optional object { timestamp, total_emails_processed, total_emails_processed_previous }`
- `timestamp: string`
- `total_emails_processed: number`
- `total_emails_processed_previous: number`
- `folder: optional "AllItems" or "Inbox"`
- `"AllItems"`
- `"Inbox"`
- `inbox_provider: optional "Microsoft" or "Google"`
- `"Microsoft"`
- `"Google"`
- `integration_id: optional string`
- `o365_tenant_id: optional string`
- `require_tls_inbound: optional boolean`
- `require_tls_outbound: optional boolean`
- `spf_status: optional "none" or "good" or "neutral" or 2 more`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
### Domain Get Response
- `DomainGetResponse = object { id, allowed_delivery_modes, created_at, 17 more }`
- `id: number`
The unique identifier for the domain.
- `allowed_delivery_modes: array of "DIRECT" or "BCC" or "JOURNAL" or 2 more`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: string`
- `domain: string`
- `drop_dispositions: array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: array of string`
- `last_modified: string`
- `lookback_hops: number`
- `regions: array of "GLOBAL" or "AU" or "DE" or 2 more`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: string`
- `authorization: optional object { authorized, timestamp, status_message }`
- `authorized: boolean`
- `timestamp: string`
- `status_message: optional string`
- `dmarc_status: optional "none" or "good" or "invalid"`
- `"none"`
- `"good"`
- `"invalid"`
- `emails_processed: optional object { timestamp, total_emails_processed, total_emails_processed_previous }`
- `timestamp: string`
- `total_emails_processed: number`
- `total_emails_processed_previous: number`
- `folder: optional "AllItems" or "Inbox"`
- `"AllItems"`
- `"Inbox"`
- `inbox_provider: optional "Microsoft" or "Google"`
- `"Microsoft"`
- `"Google"`
- `integration_id: optional string`
- `o365_tenant_id: optional string`
- `require_tls_inbound: optional boolean`
- `require_tls_outbound: optional boolean`
- `spf_status: optional "none" or "good" or "neutral" or 2 more`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
### Domain Edit Response
- `DomainEditResponse = object { id, allowed_delivery_modes, created_at, 17 more }`
- `id: number`
The unique identifier for the domain.
- `allowed_delivery_modes: array of "DIRECT" or "BCC" or "JOURNAL" or 2 more`
- `"DIRECT"`
- `"BCC"`
- `"JOURNAL"`
- `"API"`
- `"RETRO_SCAN"`
- `created_at: string`
- `domain: string`
- `drop_dispositions: array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `ip_restrictions: array of string`
- `last_modified: string`
- `lookback_hops: number`
- `regions: array of "GLOBAL" or "AU" or "DE" or 2 more`
- `"GLOBAL"`
- `"AU"`
- `"DE"`
- `"IN"`
- `"US"`
- `transport: string`
- `authorization: optional object { authorized, timestamp, status_message }`
- `authorized: boolean`
- `timestamp: string`
- `status_message: optional string`
- `dmarc_status: optional "none" or "good" or "invalid"`
- `"none"`
- `"good"`
- `"invalid"`
- `emails_processed: optional object { timestamp, total_emails_processed, total_emails_processed_previous }`
- `timestamp: string`
- `total_emails_processed: number`
- `total_emails_processed_previous: number`
- `folder: optional "AllItems" or "Inbox"`
- `"AllItems"`
- `"Inbox"`
- `inbox_provider: optional "Microsoft" or "Google"`
- `"Microsoft"`
- `"Google"`
- `integration_id: optional string`
- `o365_tenant_id: optional string`
- `require_tls_inbound: optional boolean`
- `require_tls_outbound: optional boolean`
- `spf_status: optional "none" or "good" or "neutral" or 2 more`
- `"none"`
- `"good"`
- `"neutral"`
- `"open"`
- `"invalid"`
### Domain Delete Response
- `DomainDeleteResponse = object { id }`
- `id: number`
The unique identifier for the domain.
### Domain Bulk Delete Response
- `DomainBulkDeleteResponse = object { id }`
- `id: number`
The unique identifier for the domain.
# Impersonation Registry
## List entries in impersonation registry
**get** `/accounts/{account_id}/email-security/settings/impersonation_registry`
Lists, searches, and sorts entries in the impersonation registry.
### Path Parameters
- `account_id: string`
Account Identifier
### Query Parameters
- `direction: optional "asc" or "desc"`
The sorting direction.
- `"asc"`
- `"desc"`
- `order: optional "name" or "email" or "created_at"`
The field to sort by.
- `"name"`
- `"email"`
- `"created_at"`
- `page: optional number`
The page number of paginated results.
- `per_page: optional number`
The number of results per page.
- `provenance: optional "A1S_INTERNAL" or "SNOOPY-CASB_OFFICE_365" or "SNOOPY-OFFICE_365" or "SNOOPY-GOOGLE_DIRECTORY"`
- `"A1S_INTERNAL"`
- `"SNOOPY-CASB_OFFICE_365"`
- `"SNOOPY-OFFICE_365"`
- `"SNOOPY-GOOGLE_DIRECTORY"`
- `search: optional string`
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
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { id, created_at, email, 8 more }`
- `id: number`
- `created_at: string`
- `email: string`
- `is_email_regex: boolean`
- `last_modified: string`
- `name: string`
- `comments: optional string`
- `directory_id: optional number`
- `directory_node_id: optional number`
- `external_directory_node_id: optional string`
- `provenance: optional string`
- `result_info: object { count, page, per_page, total_count }`
- `count: number`
Total number of results for the requested service
- `page: number`
Current page within paginated list of results
- `per_page: number`
Number of results per page of results
- `total_count: number`
Total results available without any search parameters
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/impersonation_registry \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**get** `/accounts/{account_id}/email-security/settings/impersonation_registry/{display_name_id}`
Retrieves a display name entry used for impersonation protection.
### Path Parameters
- `account_id: string`
Account Identifier
- `display_name_id: number`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, email, 8 more }`
- `id: number`
- `created_at: string`
- `email: string`
- `is_email_regex: boolean`
- `last_modified: string`
- `name: string`
- `comments: optional string`
- `directory_id: optional number`
- `directory_node_id: optional number`
- `external_directory_node_id: optional string`
- `provenance: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/impersonation_registry/$DISPLAY_NAME_ID \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**post** `/accounts/{account_id}/email-security/settings/impersonation_registry`
Creates a display name entry for email security impersonation protection.
### Path Parameters
- `account_id: string`
Account Identifier
### Body Parameters
- `email: string`
- `is_email_regex: boolean`
- `name: string`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, email, 8 more }`
- `id: number`
- `created_at: string`
- `email: string`
- `is_email_regex: boolean`
- `last_modified: string`
- `name: string`
- `comments: optional string`
- `directory_id: optional number`
- `directory_node_id: optional number`
- `external_directory_node_id: optional string`
- `provenance: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/impersonation_registry \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{
"email": "email",
"is_email_regex": true,
"name": "name"
}'
```
#### 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
**patch** `/accounts/{account_id}/email-security/settings/impersonation_registry/{display_name_id}`
Updates a display name entry used for impersonation protection.
### Path Parameters
- `account_id: string`
Account Identifier
- `display_name_id: number`
### Body Parameters
- `email: optional string`
- `is_email_regex: optional boolean`
- `name: optional string`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, email, 8 more }`
- `id: number`
- `created_at: string`
- `email: string`
- `is_email_regex: boolean`
- `last_modified: string`
- `name: string`
- `comments: optional string`
- `directory_id: optional number`
- `directory_node_id: optional number`
- `external_directory_node_id: optional string`
- `provenance: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/impersonation_registry/$DISPLAY_NAME_ID \
-X PATCH \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{}'
```
#### 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
**delete** `/accounts/{account_id}/email-security/settings/impersonation_registry/{display_name_id}`
Removes a display name from impersonation protection monitoring.
### Path Parameters
- `account_id: string`
Account Identifier
- `display_name_id: number`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id }`
- `id: number`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/impersonation_registry/$DISPLAY_NAME_ID \
-X DELETE \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `ImpersonationRegistryListResponse = object { id, created_at, email, 8 more }`
- `id: number`
- `created_at: string`
- `email: string`
- `is_email_regex: boolean`
- `last_modified: string`
- `name: string`
- `comments: optional string`
- `directory_id: optional number`
- `directory_node_id: optional number`
- `external_directory_node_id: optional string`
- `provenance: optional string`
### Impersonation Registry Get Response
- `ImpersonationRegistryGetResponse = object { id, created_at, email, 8 more }`
- `id: number`
- `created_at: string`
- `email: string`
- `is_email_regex: boolean`
- `last_modified: string`
- `name: string`
- `comments: optional string`
- `directory_id: optional number`
- `directory_node_id: optional number`
- `external_directory_node_id: optional string`
- `provenance: optional string`
### Impersonation Registry Create Response
- `ImpersonationRegistryCreateResponse = object { id, created_at, email, 8 more }`
- `id: number`
- `created_at: string`
- `email: string`
- `is_email_regex: boolean`
- `last_modified: string`
- `name: string`
- `comments: optional string`
- `directory_id: optional number`
- `directory_node_id: optional number`
- `external_directory_node_id: optional string`
- `provenance: optional string`
### Impersonation Registry Edit Response
- `ImpersonationRegistryEditResponse = object { id, created_at, email, 8 more }`
- `id: number`
- `created_at: string`
- `email: string`
- `is_email_regex: boolean`
- `last_modified: string`
- `name: string`
- `comments: optional string`
- `directory_id: optional number`
- `directory_node_id: optional number`
- `external_directory_node_id: optional string`
- `provenance: optional string`
### Impersonation Registry Delete Response
- `ImpersonationRegistryDeleteResponse = object { id }`
- `id: number`
# Trusted Domains
## List trusted email domains
**get** `/accounts/{account_id}/email-security/settings/trusted_domains`
Lists, searches, and sorts an account’s trusted email domains.
### Path Parameters
- `account_id: string`
Account Identifier
### Query Parameters
- `direction: optional "asc" or "desc"`
The sorting direction.
- `"asc"`
- `"desc"`
- `is_recent: optional boolean`
- `is_similarity: optional boolean`
- `order: optional "pattern" or "created_at"`
The field to sort by.
- `"pattern"`
- `"created_at"`
- `page: optional number`
The page number of paginated results.
- `pattern: optional string`
- `per_page: optional number`
The number of results per page.
- `search: optional string`
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
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
- `result_info: object { count, page, per_page, total_count }`
- `count: number`
Total number of results for the requested service
- `page: number`
Current page within paginated list of results
- `per_page: number`
Number of results per page of results
- `total_count: number`
Total results available without any search parameters
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/trusted_domains \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**get** `/accounts/{account_id}/email-security/settings/trusted_domains/{trusted_domain_id}`
Gets information about a specific trusted domain entry.
### Path Parameters
- `account_id: string`
Account Identifier
- `trusted_domain_id: number`
The unique identifier for the trusted domain.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/trusted_domains/$TRUSTED_DOMAIN_ID \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
**post** `/accounts/{account_id}/email-security/settings/trusted_domains`
Adds a domain to the trusted domains list for email security, reducing false positive
detections.
### Path Parameters
- `account_id: string`
Account Identifier
### Body Parameters
- `body: object { is_recent, is_regex, is_similarity, 2 more } or array of object { is_recent, is_regex, is_similarity, 2 more }`
- `EmailSecurityCreateTrustedDomain = object { is_recent, is_regex, is_similarity, 2 more }`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
Select for partner or other approved domains that have similar
spelling to your connected domains. Prevents listed domains from
triggering a Spoof disposition.
- `pattern: string`
- `comments: optional string`
- `array of object { is_recent, is_regex, is_similarity, 2 more }`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
Select for partner or other approved domains that have similar
spelling to your connected domains. Prevents listed domains from
triggering a Spoof disposition.
- `pattern: string`
- `comments: optional string`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, is_recent, 5 more } or array of object { id, created_at, is_recent, 5 more }`
- `EmailSecurityTrustedDomain = object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
- `array of object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/trusted_domains \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{
"is_recent": true,
"is_regex": false,
"is_similarity": false,
"pattern": "example.com"
}'
```
#### 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
**patch** `/accounts/{account_id}/email-security/settings/trusted_domains/{trusted_domain_id}`
Modifies a trusted domain entry's configuration.
### Path Parameters
- `account_id: string`
Account Identifier
- `trusted_domain_id: number`
The unique identifier for the trusted domain.
### Body Parameters
- `comments: optional string`
- `is_recent: optional boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: optional boolean`
- `is_similarity: optional boolean`
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 string`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/trusted_domains/$TRUSTED_DOMAIN_ID \
-X PATCH \
-H 'Content-Type: application/json' \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
-d '{}'
```
#### 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
**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.
### Path Parameters
- `account_id: string`
Account Identifier
- `trusted_domain_id: number`
The unique identifier for the trusted domain.
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: object { id }`
- `id: number`
The unique identifier for the trusted domain.
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/trusted_domains/$TRUSTED_DOMAIN_ID \
-X DELETE \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `TrustedDomainListResponse = object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
### Trusted Domain Get Response
- `TrustedDomainGetResponse = object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
### Trusted Domain Create Response
- `TrustedDomainCreateResponse = object { id, created_at, is_recent, 5 more } or array of object { id, created_at, is_recent, 5 more }`
- `EmailSecurityTrustedDomain = object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
- `array of object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
### Trusted Domain Edit Response
- `TrustedDomainEditResponse = object { id, created_at, is_recent, 5 more }`
- `id: number`
The unique identifier for the trusted domain.
- `created_at: string`
- `is_recent: boolean`
Select to prevent recently registered domains from triggering a
Suspicious or Malicious disposition.
- `is_regex: boolean`
- `is_similarity: boolean`
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: string`
- `pattern: string`
- `comments: optional string`
### Trusted Domain Delete Response
- `TrustedDomainDeleteResponse = object { id }`
- `id: number`
The unique identifier for the trusted domain.
# Submissions
## Get reclassify submissions
**get** `/accounts/{account_id}/email-security/submissions`
This endpoint returns information for submissions to made to reclassify emails.
### Path Parameters
- `account_id: string`
Account Identifier
### Query Parameters
- `customer_status: optional "escalated" or "reviewed" or "unreviewed"`
- `"escalated"`
- `"reviewed"`
- `"unreviewed"`
- `end: optional string`
The end of the search date range.
Defaults to `now` if not provided.
- `original_disposition: optional "MALICIOUS" or "SUSPICIOUS" or "SPOOF" or 3 more`
- `"MALICIOUS"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"NONE"`
- `outcome_disposition: optional "MALICIOUS" or "SUSPICIOUS" or "SPOOF" or 3 more`
- `"MALICIOUS"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"NONE"`
- `page: optional number`
The page number of paginated results.
- `per_page: optional number`
The number of results per page.
- `query: optional string`
- `requested_disposition: optional "MALICIOUS" or "SUSPICIOUS" or "SPOOF" or 3 more`
- `"MALICIOUS"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"NONE"`
- `start: optional string`
The beginning of the search date range.
Defaults to `now - 30 days` if not provided.
- `status: optional string`
- `submission_id: optional string`
- `type: optional "TEAM" or "USER"`
- `"TEAM"`
- `"USER"`
### Returns
- `errors: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `pointer: optional string`
- `messages: array of ResponseInfo`
- `code: number`
- `message: string`
- `documentation_url: optional string`
- `source: optional object { pointer }`
- `result: array of object { requested_ts, submission_id, customer_status, 15 more }`
- `requested_ts: string`
deprecated as of 2026-04-01, use `requested_at` instead.
- `submission_id: string`
- `customer_status: optional "escalated" or "reviewed" or "unreviewed"`
- `"escalated"`
- `"reviewed"`
- `"unreviewed"`
- `escalated_as: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `escalated_at: optional string`
- `escalated_by: optional string`
- `escalated_submission_id: optional string`
- `original_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `original_edf_hash: optional string`
- `original_postfix_id: optional string`
- `outcome: optional string`
- `outcome_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `requested_at: optional string`
- `requested_by: optional string`
- `requested_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `status: optional string`
- `subject: optional string`
- `type: optional string`
- `result_info: object { count, page, per_page, total_count }`
- `count: number`
Total number of results for the requested service
- `page: number`
Current page within paginated list of results
- `per_page: number`
Number of results per page of results
- `total_count: number`
Total results available without any search parameters
- `success: boolean`
### Example
```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/submissions \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```
#### 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
- `SubmissionListResponse = object { requested_ts, submission_id, customer_status, 15 more }`
- `requested_ts: string`
deprecated as of 2026-04-01, use `requested_at` instead.
- `submission_id: string`
- `customer_status: optional "escalated" or "reviewed" or "unreviewed"`
- `"escalated"`
- `"reviewed"`
- `"unreviewed"`
- `escalated_as: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `escalated_at: optional string`
- `escalated_by: optional string`
- `escalated_submission_id: optional string`
- `original_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `original_edf_hash: optional string`
- `original_postfix_id: optional string`
- `outcome: optional string`
- `outcome_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `requested_at: optional string`
- `requested_by: optional string`
- `requested_disposition: optional "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more`
- `"MALICIOUS"`
- `"MALICIOUS-BEC"`
- `"SUSPICIOUS"`
- `"SPOOF"`
- `"SPAM"`
- `"BULK"`
- `"ENCRYPTED"`
- `"EXTERNAL"`
- `"UNKNOWN"`
- `"NONE"`
- `status: optional string`
- `subject: optional string`
- `type: optional string`