Batch domain operations

POST/accounts/{account_id}/email-security/settings/domains/batch

Executes multiple domain operations in a single request. All four operation arrays (deletes, patches, puts, posts) are required and executed in order. Send empty arrays for unused operations.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Cloud Email Security: Write

Path ParametersExpand Collapse

account_id: string

Identifier.

maxLength32

Body ParametersJSONExpand Collapse

deletes: array of object { id }

id: string

Domain identifier.

formatuuid

patches: array of object { id, allowed_delivery_modes, drop_dispositions, 8 more }

id: string

Domain identifier.

formatuuid

allowed_delivery_modes: optional array of "DIRECT" or "BCC" or "JOURNAL" or 2 more

One of the following:

"DIRECT"

"BCC"

"JOURNAL"

"API"

"RETRO_SCAN"

drop_dispositions: optional array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more

One of the following:

"MALICIOUS"

"MALICIOUS-BEC"

"SUSPICIOUS"

"SPOOF"

"SPAM"

"BULK"

"ENCRYPTED"

"EXTERNAL"

"UNKNOWN"

"NONE"

folder: optional "AllItems" or "Inbox"

One of the following:

"AllItems"

"Inbox"

integration_id: optional string

formatuuid

ip_restrictions: optional array of string

lookback_hops: optional number

maximum20

minimum1

regions: optional array of "GLOBAL" or "AU" or "DE" or 2 more

One of the following:

"GLOBAL"

"AU"

"DE"

"IN"

"US"

require_tls_inbound: optional boolean

require_tls_outbound: optional boolean

transport: optional string

posts: array of object { allowed_delivery_modes, domain, drop_dispositions, 8 more }

allowed_delivery_modes: array of "DIRECT" or "BCC" or "JOURNAL" or 2 more

One of the following:

"DIRECT"

"BCC"

"JOURNAL"

"API"

"RETRO_SCAN"

domain: string

drop_dispositions: array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more

One of the following:

"MALICIOUS"

"MALICIOUS-BEC"

"SUSPICIOUS"

"SPOOF"

"SPAM"

"BULK"

"ENCRYPTED"

"EXTERNAL"

"UNKNOWN"

"NONE"

ip_restrictions: array of string

regions: array of "GLOBAL" or "AU" or "DE" or 2 more

One of the following:

"GLOBAL"

"AU"

"DE"

"IN"

"US"

folder: optional "AllItems" or "Inbox"

One of the following:

"AllItems"

"Inbox"

integration_id: optional string

formatuuid

lookback_hops: optional number

maximum20

minimum1

require_tls_inbound: optional boolean

require_tls_outbound: optional boolean

transport: optional string

puts: array of object { id, allowed_delivery_modes, drop_dispositions, 8 more }

id: string

Domain identifier.

formatuuid

allowed_delivery_modes: array of "DIRECT" or "BCC" or "JOURNAL" or 2 more

One of the following:

"DIRECT"

"BCC"

"JOURNAL"

"API"

"RETRO_SCAN"

drop_dispositions: array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more

One of the following:

"MALICIOUS"

"MALICIOUS-BEC"

"SUSPICIOUS"

"SPOOF"

"SPAM"

"BULK"

"ENCRYPTED"

"EXTERNAL"

"UNKNOWN"

"NONE"

ip_restrictions: array of string

regions: array of "GLOBAL" or "AU" or "DE" or 2 more

One of the following:

"GLOBAL"

"AU"

"DE"

"IN"

"US"

folder: optional "AllItems" or "Inbox"

One of the following:

"AllItems"

"Inbox"

integration_id: optional string

formatuuid

lookback_hops: optional number

maximum20

minimum1

require_tls_inbound: optional boolean

require_tls_outbound: optional boolean

transport: optional string

ReturnsExpand Collapse

errors: array of object { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

messages: array of object { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

success: true

Whether the API call was successful.

result: optional object { deletes, patches, posts, puts }

deletes: array of object { id }

id: string

Domain identifier.

formatuuid

patches: array of object { id, allowed_delivery_modes, authorization, 19 more }

id: optional string

Domain identifier.

formatuuid

allowed_delivery_modes: optional array of "DIRECT" or "BCC" or "JOURNAL" or 2 more

One of the following:

"DIRECT"

"BCC"

"JOURNAL"

"API"

"RETRO_SCAN"

authorization: optional object { authorized, timestamp, status_message }

authorized: boolean

timestamp: string

formatdate-time

status_message: optional string

created_at: optional string

formatdate-time

dmarc_status: optional "none" or "good" or "invalid"

One of the following:

"none"

"good"

"invalid"

domain: optional string

drop_dispositions: optional array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more

One of the following:

"MALICIOUS"

"MALICIOUS-BEC"

"SUSPICIOUS"

"SPOOF"

"SPAM"

"BULK"

"ENCRYPTED"

"EXTERNAL"

"UNKNOWN"

"NONE"

emails_processed: optional object { timestamp, total_emails_processed, total_emails_processed_previous }

timestamp: string

formatdate-time

total_emails_processed: number

minimum0

total_emails_processed_previous: number

minimum0

folder: optional "AllItems" or "Inbox"

One of the following:

"AllItems"

"Inbox"

inbox_provider: optional "Microsoft" or "Google"

One of the following:

"Microsoft"

"Google"

integration_id: optional string

formatuuid

ip_restrictions: optional array of string

Deprecatedlast_modified: optional string

Use modified_at instead.

Deprecated, use modified_at instead. End of life: November 1, 2026.

formatdate-time

lookback_hops: optional number

modified_at: optional string

formatdate-time

o365_tenant_id: optional string

regions: optional array of "GLOBAL" or "AU" or "DE" or 2 more

One of the following:

"GLOBAL"

"AU"

"DE"

"IN"

"US"

require_tls_inbound: optional boolean

require_tls_outbound: optional boolean

spf_status: optional "none" or "good" or "neutral" or 2 more

One of the following:

"none"

"good"

"neutral"

"open"

"invalid"

status: optional "PENDING" or "ACTIVE" or "FAILED" or "TIMEOUT"

One of the following:

"PENDING"

"ACTIVE"

"FAILED"

"TIMEOUT"

transport: optional string

posts: array of object { id, allowed_delivery_modes, authorization, 19 more }

id: optional string

Domain identifier.

formatuuid

allowed_delivery_modes: optional array of "DIRECT" or "BCC" or "JOURNAL" or 2 more

One of the following:

"DIRECT"

"BCC"

"JOURNAL"

"API"

"RETRO_SCAN"

authorization: optional object { authorized, timestamp, status_message }

authorized: boolean

timestamp: string

formatdate-time

status_message: optional string

created_at: optional string

formatdate-time

dmarc_status: optional "none" or "good" or "invalid"

One of the following:

"none"

"good"

"invalid"

domain: optional string

drop_dispositions: optional array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more

One of the following:

"MALICIOUS"

"MALICIOUS-BEC"

"SUSPICIOUS"

"SPOOF"

"SPAM"

"BULK"

"ENCRYPTED"

"EXTERNAL"

"UNKNOWN"

"NONE"

emails_processed: optional object { timestamp, total_emails_processed, total_emails_processed_previous }

timestamp: string

formatdate-time

total_emails_processed: number

minimum0

total_emails_processed_previous: number

minimum0

folder: optional "AllItems" or "Inbox"

One of the following:

"AllItems"

"Inbox"

inbox_provider: optional "Microsoft" or "Google"

One of the following:

"Microsoft"

"Google"

integration_id: optional string

formatuuid

ip_restrictions: optional array of string

Deprecatedlast_modified: optional string

Use modified_at instead.

Deprecated, use modified_at instead. End of life: November 1, 2026.

formatdate-time

lookback_hops: optional number

modified_at: optional string

formatdate-time

o365_tenant_id: optional string

regions: optional array of "GLOBAL" or "AU" or "DE" or 2 more

One of the following:

"GLOBAL"

"AU"

"DE"

"IN"

"US"

require_tls_inbound: optional boolean

require_tls_outbound: optional boolean

spf_status: optional "none" or "good" or "neutral" or 2 more

One of the following:

"none"

"good"

"neutral"

"open"

"invalid"

status: optional "PENDING" or "ACTIVE" or "FAILED" or "TIMEOUT"

One of the following:

"PENDING"

"ACTIVE"

"FAILED"

"TIMEOUT"

transport: optional string

puts: array of object { id, allowed_delivery_modes, authorization, 19 more }

id: optional string

Domain identifier.

formatuuid

allowed_delivery_modes: optional array of "DIRECT" or "BCC" or "JOURNAL" or 2 more

One of the following:

"DIRECT"

"BCC"

"JOURNAL"

"API"

"RETRO_SCAN"

authorization: optional object { authorized, timestamp, status_message }

authorized: boolean

timestamp: string

formatdate-time

status_message: optional string

created_at: optional string

formatdate-time

dmarc_status: optional "none" or "good" or "invalid"

One of the following:

"none"

"good"

"invalid"

domain: optional string

drop_dispositions: optional array of "MALICIOUS" or "MALICIOUS-BEC" or "SUSPICIOUS" or 7 more

One of the following:

"MALICIOUS"

"MALICIOUS-BEC"

"SUSPICIOUS"

"SPOOF"

"SPAM"

"BULK"

"ENCRYPTED"

"EXTERNAL"

"UNKNOWN"

"NONE"

emails_processed: optional object { timestamp, total_emails_processed, total_emails_processed_previous }

timestamp: string

formatdate-time

total_emails_processed: number

minimum0

total_emails_processed_previous: number

minimum0

folder: optional "AllItems" or "Inbox"

One of the following:

"AllItems"

"Inbox"

inbox_provider: optional "Microsoft" or "Google"

One of the following:

"Microsoft"

"Google"

integration_id: optional string

formatuuid

ip_restrictions: optional array of string

Deprecatedlast_modified: optional string

Use modified_at instead.

Deprecated, use modified_at instead. End of life: November 1, 2026.

formatdate-time

lookback_hops: optional number

modified_at: optional string

formatdate-time

o365_tenant_id: optional string

regions: optional array of "GLOBAL" or "AU" or "DE" or 2 more

One of the following:

"GLOBAL"

"AU"

"DE"

"IN"

"US"

require_tls_inbound: optional boolean

require_tls_outbound: optional boolean

spf_status: optional "none" or "good" or "neutral" or 2 more

One of the following:

"none"

"good"

"neutral"

"open"

"invalid"

status: optional "PENDING" or "ACTIVE" or "FAILED" or "TIMEOUT"

One of the following:

"PENDING"

"ACTIVE"

"FAILED"

"TIMEOUT"

transport: optional string

Batch domain operations

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email-security/settings/domains/batch \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "deletes": [
            {
              "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
            }
          ],
          "patches": [
            {
              "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
            }
          ],
          "posts": [
            {
              "allowed_delivery_modes": [
                "DIRECT"
              ],
              "domain": "domain",
              "drop_dispositions": [
                "MALICIOUS"
              ],
              "ip_restrictions": [
                "192.0.2.0/24",
                "2001:db8::/32"
              ],
              "regions": [
                "GLOBAL"
              ]
            }
          ],
          "puts": [
            {
              "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
              "allowed_delivery_modes": [
                "DIRECT"
              ],
              "drop_dispositions": [
                "MALICIOUS"
              ],
              "ip_restrictions": [
                "192.0.2.0/24",
                "2001:db8::/32"
              ],
              "regions": [
                "GLOBAL"
              ]
            }
          ]
        }'

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "deletes": [
      {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
      }
    ],
    "patches": [
      {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "allowed_delivery_modes": [
          "DIRECT"
        ],
        "authorization": {
          "authorized": true,
          "timestamp": "2019-12-27T18:11:19.117Z",
          "status_message": "status_message"
        },
        "created_at": "2014-01-01T05:20:00.12345Z",
        "dmarc_status": "none",
        "domain": "example.com",
        "drop_dispositions": [
          "MALICIOUS"
        ],
        "emails_processed": {
          "timestamp": "2019-12-27T18:11:19.117Z",
          "total_emails_processed": 0,
          "total_emails_processed_previous": 0
        },
        "folder": "AllItems",
        "inbox_provider": "Microsoft",
        "integration_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "ip_restrictions": [
          "192.0.2.0/24",
          "2001:db8::/32"
        ],
        "last_modified": "2014-01-01T05:20:00.12345Z",
        "lookback_hops": 0,
        "modified_at": "2014-01-01T05:20:00.12345Z",
        "o365_tenant_id": "o365_tenant_id",
        "regions": [
          "GLOBAL"
        ],
        "require_tls_inbound": true,
        "require_tls_outbound": true,
        "spf_status": "none",
        "status": "PENDING",
        "transport": "transport"
      }
    ],
    "posts": [
      {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "allowed_delivery_modes": [
          "DIRECT"
        ],
        "authorization": {
          "authorized": true,
          "timestamp": "2019-12-27T18:11:19.117Z",
          "status_message": "status_message"
        },
        "created_at": "2014-01-01T05:20:00.12345Z",
        "dmarc_status": "none",
        "domain": "example.com",
        "drop_dispositions": [
          "MALICIOUS"
        ],
        "emails_processed": {
          "timestamp": "2019-12-27T18:11:19.117Z",
          "total_emails_processed": 0,
          "total_emails_processed_previous": 0
        },
        "folder": "AllItems",
        "inbox_provider": "Microsoft",
        "integration_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "ip_restrictions": [
          "192.0.2.0/24",
          "2001:db8::/32"
        ],
        "last_modified": "2014-01-01T05:20:00.12345Z",
        "lookback_hops": 0,
        "modified_at": "2014-01-01T05:20:00.12345Z",
        "o365_tenant_id": "o365_tenant_id",
        "regions": [
          "GLOBAL"
        ],
        "require_tls_inbound": true,
        "require_tls_outbound": true,
        "spf_status": "none",
        "status": "PENDING",
        "transport": "transport"
      }
    ],
    "puts": [
      {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "allowed_delivery_modes": [
          "DIRECT"
        ],
        "authorization": {
          "authorized": true,
          "timestamp": "2019-12-27T18:11:19.117Z",
          "status_message": "status_message"
        },
        "created_at": "2014-01-01T05:20:00.12345Z",
        "dmarc_status": "none",
        "domain": "example.com",
        "drop_dispositions": [
          "MALICIOUS"
        ],
        "emails_processed": {
          "timestamp": "2019-12-27T18:11:19.117Z",
          "total_emails_processed": 0,
          "total_emails_processed_previous": 0
        },
        "folder": "AllItems",
        "inbox_provider": "Microsoft",
        "integration_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "ip_restrictions": [
          "192.0.2.0/24",
          "2001:db8::/32"
        ],
        "last_modified": "2014-01-01T05:20:00.12345Z",
        "lookback_hops": 0,
        "modified_at": "2014-01-01T05:20:00.12345Z",
        "o365_tenant_id": "o365_tenant_id",
        "regions": [
          "GLOBAL"
        ],
        "require_tls_inbound": true,
        "require_tls_outbound": true,
        "spf_status": "none",
        "status": "PENDING",
        "transport": "transport"
      }
    ]
  }
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "deletes": [
      {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
      }
    ],
    "patches": [
      {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "allowed_delivery_modes": [
          "DIRECT"
        ],
        "authorization": {
          "authorized": true,
          "timestamp": "2019-12-27T18:11:19.117Z",
          "status_message": "status_message"
        },
        "created_at": "2014-01-01T05:20:00.12345Z",
        "dmarc_status": "none",
        "domain": "example.com",
        "drop_dispositions": [
          "MALICIOUS"
        ],
        "emails_processed": {
          "timestamp": "2019-12-27T18:11:19.117Z",
          "total_emails_processed": 0,
          "total_emails_processed_previous": 0
        },
        "folder": "AllItems",
        "inbox_provider": "Microsoft",
        "integration_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "ip_restrictions": [
          "192.0.2.0/24",
          "2001:db8::/32"
        ],
        "last_modified": "2014-01-01T05:20:00.12345Z",
        "lookback_hops": 0,
        "modified_at": "2014-01-01T05:20:00.12345Z",
        "o365_tenant_id": "o365_tenant_id",
        "regions": [
          "GLOBAL"
        ],
        "require_tls_inbound": true,
        "require_tls_outbound": true,
        "spf_status": "none",
        "status": "PENDING",
        "transport": "transport"
      }
    ],
    "posts": [
      {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "allowed_delivery_modes": [
          "DIRECT"
        ],
        "authorization": {
          "authorized": true,
          "timestamp": "2019-12-27T18:11:19.117Z",
          "status_message": "status_message"
        },
        "created_at": "2014-01-01T05:20:00.12345Z",
        "dmarc_status": "none",
        "domain": "example.com",
        "drop_dispositions": [
          "MALICIOUS"
        ],
        "emails_processed": {
          "timestamp": "2019-12-27T18:11:19.117Z",
          "total_emails_processed": 0,
          "total_emails_processed_previous": 0
        },
        "folder": "AllItems",
        "inbox_provider": "Microsoft",
        "integration_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "ip_restrictions": [
          "192.0.2.0/24",
          "2001:db8::/32"
        ],
        "last_modified": "2014-01-01T05:20:00.12345Z",
        "lookback_hops": 0,
        "modified_at": "2014-01-01T05:20:00.12345Z",
        "o365_tenant_id": "o365_tenant_id",
        "regions": [
          "GLOBAL"
        ],
        "require_tls_inbound": true,
        "require_tls_outbound": true,
        "spf_status": "none",
        "status": "PENDING",
        "transport": "transport"
      }
    ],
    "puts": [
      {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "allowed_delivery_modes": [
          "DIRECT"
        ],
        "authorization": {
          "authorized": true,
          "timestamp": "2019-12-27T18:11:19.117Z",
          "status_message": "status_message"
        },
        "created_at": "2014-01-01T05:20:00.12345Z",
        "dmarc_status": "none",
        "domain": "example.com",
        "drop_dispositions": [
          "MALICIOUS"
        ],
        "emails_processed": {
          "timestamp": "2019-12-27T18:11:19.117Z",
          "total_emails_processed": 0,
          "total_emails_processed_previous": 0
        },
        "folder": "AllItems",
        "inbox_provider": "Microsoft",
        "integration_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "ip_restrictions": [
          "192.0.2.0/24",
          "2001:db8::/32"
        ],
        "last_modified": "2014-01-01T05:20:00.12345Z",
        "lookback_hops": 0,
        "modified_at": "2014-01-01T05:20:00.12345Z",
        "o365_tenant_id": "o365_tenant_id",
        "regions": [
          "GLOBAL"
        ],
        "require_tls_inbound": true,
        "require_tls_outbound": true,
        "spf_status": "none",
        "status": "PENDING",
        "transport": "transport"
      }
    ]
  }
}