# 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.