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, domain, 9 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, domain, 9 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"
domain?: string

Body param

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"

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

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
One of the following:
"none"
"good"
"neutral"
"open"
"invalid"
status?: "pending" | "active" | "failed" | "timeout"
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"
  }
}