subdomains

Creates, updates, deletes, gets or lists a subdomains resource.

Overview

Name	subdomains
Type	Resource
Id	cloudflare.email_sending.subdomains

Fields

The following fields are returned by SELECT queries:

get

Get a sending subdomain response

Name	Datatype	Description
errors	array
messages	array
result	object
success	boolean	Whether the API call was successful. (true)

list

List sending subdomains response

Name	Datatype	Description
name	string	The subdomain domain name. (example: sub.example.com)
created	string (date-time)	The date and time the destination address has been created. (example: 2014-01-02T02:20:00Z)
dkim_selector	string	The DKIM selector used for email signing. (example: cf-bounce)
enabled	boolean	Whether Email Sending is enabled on this subdomain.
modified	string (date-time)	The date and time the destination address was last modified. (example: 2014-01-02T02:20:00Z)
return_path_domain	string	The return-path domain used for bounce handling. (example: cf-bounce.sub.example.com)
tag	string	Sending subdomain identifier. (example: aabbccdd11223344aabbccdd11223344)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	subdomain_id, zone_id		Gets information for a specific sending subdomain.
list	select	zone_id		Lists all sending-enabled subdomains for the zone.
create	insert	zone_id, name		Creates a new sending subdomain or re-enables sending on an existing subdomain that had it disabled. If zone-level Email Sending has not been enabled yet, the zone flag is automatically set when the entitlement is present.
delete	delete	subdomain_id, zone_id		Disables sending on a subdomain and removes its DNS records. If routing is still active on the subdomain, only sending is disabled.
preview	exec	zone_id, name		Returns the DNS records that would be created for a sending subdomain, flags which records are missing, and reports any conflicts with existing DNS records. This is a read-only dry-run — no records are created or modified. Use before or after creating a subdomain to check DNS status.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
subdomain_id	string
zone_id	string	The Cloudflare zone ID.

SELECT examples

get

Gets information for a specific sending subdomain.

SELECT
errors,
messages,
result,
success
FROM cloudflare.email_sending.subdomains
WHERE subdomain_id = '{{ subdomain_id }}' -- required
AND zone_id = '{{ zone_id }}' -- required
;

list

Lists all sending-enabled subdomains for the zone.

SELECT
name,
created,
dkim_selector,
enabled,
modified,
return_path_domain,
tag
FROM cloudflare.email_sending.subdomains
WHERE zone_id = '{{ zone_id }}' -- required
;

INSERT examples

create

Creates a new sending subdomain or re-enables sending on an existing subdomain that had it disabled. If zone-level Email Sending has not been enabled yet, the zone flag is automatically set when the entitlement is present.

INSERT INTO cloudflare.email_sending.subdomains (
name,
zone_id
)
SELECT 
'{{ name }}' /* required */,
'{{ zone_id }}'
RETURNING
errors,
messages,
result,
success
;

Manifest

# Description fields are for documentation purposes
- name: subdomains
props:
  - name: zone_id
    value: "{{ zone_id }}"
    description: Required parameter for the subdomains resource.
  - name: name
    value: "{{ name }}"
    description: |
      The subdomain name. Must be within the zone.

DELETE examples

delete

Disables sending on a subdomain and removes its DNS records. If routing is still active on the subdomain, only sending is disabled.

DELETE FROM cloudflare.email_sending.subdomains
WHERE subdomain_id = '{{ subdomain_id }}' --required
AND zone_id = '{{ zone_id }}' --required
;

Lifecycle Methods

preview

Returns the DNS records that would be created for a sending subdomain, flags which records are missing, and reports any conflicts with existing DNS records. This is a read-only dry-run — no records are created or modified. Use before or after creating a subdomain to check DNS status.

EXEC cloudflare.email_sending.subdomains.preview 
@zone_id='{{ zone_id }}' --required 
@@json=
'{
"name": "{{ name }}"
}'
;