Skip to content
Cloudflare API
Start here
API Reference
Email Security
Settings
Domains

Update an email domain

client.emailSecurity.settings.domains.edit(stringdomainID, DomainEditParams { account_id, allowed_delivery_modes, drop_dispositions, 8 more } params, RequestOptionsoptions?): DomainEditResponse { id, allowed_delivery_modes, authorization, 19 more }
PATCH/accounts/{account_id}/email-security/settings/domains/{domain_id}

Updates configuration for a protected email domain. Only provided fields will be modified. Changes affect delivery mode, security settings, and regional processing.

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
ParametersExpand Collapse
domainID: string

Domain identifier.

formatuuid
params: DomainEditParams { account_id, allowed_delivery_modes, drop_dispositions, 8 more }
account_id: string

Path param: Identifier.

maxLength32
allowed_delivery_modes?: Array<"DIRECT" | "BCC" | "JOURNAL" | 2 more>

Body param

One of the following:
"DIRECT"
"BCC"
"JOURNAL"
"API"
"RETRO_SCAN"
drop_dispositions?: Array<"MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more>

Body param

One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
folder?: "AllItems" | "Inbox" | null

Body param

One of the following:
"AllItems"
"Inbox"
integration_id?: string | null

Body param

formatuuid
ip_restrictions?: Array<string>

Body param

lookback_hops?: number

Body param

maximum20
minimum1
regions?: Array<"GLOBAL" | "AU" | "DE" | 2 more>

Body param

One of the following:
"GLOBAL"
"AU"
"DE"
"IN"
"US"
require_tls_inbound?: boolean

Body param

require_tls_outbound?: boolean

Body param

transport?: string

Body param

ReturnsExpand Collapse
DomainEditResponse { id, allowed_delivery_modes, authorization, 19 more }
id?: string

Domain identifier.

formatuuid
allowed_delivery_modes?: Array<"DIRECT" | "BCC" | "JOURNAL" | 2 more>
One of the following:
"DIRECT"
"BCC"
"JOURNAL"
"API"
"RETRO_SCAN"
authorization?: Authorization { authorized, timestamp, status_message }
authorized: boolean
timestamp: string
formatdate-time
status_message?: string | null
created_at?: string
formatdate-time
dmarc_status?: "none" | "good" | "invalid" | null
One of the following:
"none"
"good"
"invalid"
domain?: string
drop_dispositions?: Array<"MALICIOUS" | "MALICIOUS-BEC" | "SUSPICIOUS" | 7 more>
One of the following:
"MALICIOUS"
"MALICIOUS-BEC"
"SUSPICIOUS"
"SPOOF"
"SPAM"
"BULK"
"ENCRYPTED"
"EXTERNAL"
"UNKNOWN"
"NONE"
emails_processed?: EmailsProcessed { timestamp, total_emails_processed, total_emails_processed_previous }
timestamp: string
formatdate-time
total_emails_processed: number
minimum0
total_emails_processed_previous: number
minimum0
folder?: "AllItems" | "Inbox" | null
One of the following:
"AllItems"
"Inbox"
inbox_provider?: "Microsoft" | "Google" | null
One of the following:
"Microsoft"
"Google"
integration_id?: string | null
formatuuid
ip_restrictions?: Array<string>
Deprecatedlast_modified?: string

Use modified_at instead.

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

formatdate-time
lookback_hops?: number
modified_at?: string
formatdate-time
o365_tenant_id?: string | null
regions?: Array<"GLOBAL" | "AU" | "DE" | 2 more>
One of the following:
"GLOBAL"
"AU"
"DE"
"IN"
"US"
require_tls_inbound?: boolean | null
require_tls_outbound?: boolean | null
spf_status?: "none" | "good" | "neutral" | 2 more | null
One of the following:
"none"
"good"
"neutral"
"open"
"invalid"
status?: "PENDING" | "ACTIVE" | "FAILED" | "TIMEOUT" | null
One of the following:
"PENDING"
"ACTIVE"
"FAILED"
"TIMEOUT"
transport?: string

Update an email domain

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const response = await client.emailSecurity.settings.domains.edit(
  'f174e90a-fafe-4643-bbbc-4a0ed4fc8415',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

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