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: Delivery modes to onboard the domain through.

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

Body param: Dispositions to drop instead of delivering, e.g. ["MALICIOUS", "SPAM"].

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

Body param: The mailbox folder to scan, for API-scanning domains.

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

Body param: Identifier of the CASB integration that authorizes this domain. The integration also enables API scanning, post-delivery actions, and directory sync.

formatuuid
ip_restrictions?: Array<string>

Body param: Source IP ranges mail is accepted from. Any other source is rejected.

lookback_hops?: number

Body param: Number of hops to trace back through received headers when reconstructing the original message (1-20).

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

Body param: Regions that process messages for this domain, e.g. ["GLOBAL"] or ["US"].

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

Body param: Require TLS on inbound connections.

require_tls_outbound?: boolean

Body param: Require TLS on outbound connections.

transport?: string

Body param: The mail transport hostname for MX/Inline delivery — the MX record Cloudflare delivers email to (e.g. mx.example.com).

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 | null
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 | null
timestamp: string
formatdate-time
total_emails_processed: number
minimum0
total_emails_processed_previous: number
minimum0
folder?: "AllItems" | "Inbox" | null

The mailbox folder to scan, for API-scanning domains.

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"
  }
}