Skip to content
Cloudflare API
Start here
API Reference

Email Sending

Send an email
email_sending.send(EmailSendingSendParams**kwargs) -> EmailSendingSendResponse
POST/accounts/{account_id}/email/sending/send
Send a raw MIME email
email_sending.send_raw(EmailSendingSendRawParams**kwargs) -> EmailSendingSendRawResponse
POST/accounts/{account_id}/email/sending/send_raw
ModelsExpand Collapse
class EmailSendingSendResponse: …
delivered: List[str]

Email addresses to which the message was delivered immediately.

message_id: str

Message ID of the sent email.

permanent_bounces: List[str]

Email addresses that permanently bounced.

queued: List[str]

Email addresses for which delivery was queued for later.

suppressed_recipients: List[str]

Email addresses dropped because they are on the suppression list. Returned when suppressed-recipient dropping is enabled for the sending subdomain; otherwise the request fails instead.

class EmailSendingSendRawResponse: …
delivered: List[str]

Email addresses to which the message was delivered immediately.

message_id: str

Message ID of the sent email.

permanent_bounces: List[str]

Email addresses that permanently bounced.

queued: List[str]

Email addresses for which delivery was queued for later.

suppressed_recipients: List[str]

Email addresses dropped because they are on the suppression list. Returned when suppressed-recipient dropping is enabled for the sending subdomain; otherwise the request fails instead.

Email SendingSuppressions

List account Email Sending suppressions
email_sending.suppressions.list(SuppressionListParams**kwargs) -> SyncCursorPagination[SuppressionListResponse]
GET/accounts/{account_id}/email/sending/suppressions
Get account Email Sending suppression
email_sending.suppressions.get(strsuppression_id, SuppressionGetParams**kwargs) -> SuppressionGetResponse
GET/accounts/{account_id}/email/sending/suppressions/{suppression_id}
Create account Email Sending suppression
email_sending.suppressions.create(SuppressionCreateParams**kwargs) -> SuppressionCreateResponse
POST/accounts/{account_id}/email/sending/suppressions
Update account Email Sending suppression
email_sending.suppressions.edit(strsuppression_id, SuppressionEditParams**kwargs) -> SuppressionEditResponse
PATCH/accounts/{account_id}/email/sending/suppressions/{suppression_id}
Delete account Email Sending suppression
email_sending.suppressions.delete(strsuppression_id, SuppressionDeleteParams**kwargs) -> SuppressionDeleteResponse
DELETE/accounts/{account_id}/email/sending/suppressions/{suppression_id}
Bulk import account Email Sending suppressions
email_sending.suppressions.import_(SuppressionImportParams**kwargs) -> SuppressionImportResponse
POST/accounts/{account_id}/email/sending/suppressions/bulk
ModelsExpand Collapse
class SuppressionListResponse: …
id: str

Unique identifier for this suppression.

formatuuid
created_at: datetime

When the suppression was created.

formatdate-time
email: str

The suppressed email address.

formatemail
expires_at: Optional[datetime]

When the suppression expires. Null for a permanent suppression.

formatdate-time
read_only: bool

Whether clients may mutate this suppression. This is determined by the server and must not be inferred from reason.

reason: str

Why the address is suppressed: manual, complaint, hard_bounce, soft_bounce, or policy.

note: Optional[str]

Advisory note for this suppression, if any.

scope: Optional[Scope]

Where the suppression applies: account for every sending domain of the account, or sending_domain for one envelope MAIL FROM domain.

One of the following:
class ScopeType: …
type: Literal["account"]

Blocks the recipient for every sending domain of the account.

class ScopeUnionMember1: …
type: Literal["sending_domain"]

Blocks the recipient only for mail whose envelope MAIL FROM uses value.

value: str

The sending domain: the domain part of the envelope MAIL FROM, lowercase, without a trailing dot.

maxLength1024
class SuppressionGetResponse: …
id: str

Unique identifier for this suppression.

formatuuid
created_at: datetime

When the suppression was created.

formatdate-time
email: str

The suppressed email address.

formatemail
expires_at: Optional[datetime]

When the suppression expires. Null for a permanent suppression.

formatdate-time
read_only: bool

Whether clients may mutate this suppression. This is determined by the server and must not be inferred from reason.

reason: str

Why the address is suppressed: manual, complaint, hard_bounce, soft_bounce, or policy.

note: Optional[str]

Advisory note for this suppression, if any.

scope: Optional[Scope]

Where the suppression applies: account for every sending domain of the account, or sending_domain for one envelope MAIL FROM domain.

One of the following:
class ScopeType: …
type: Literal["account"]

Blocks the recipient for every sending domain of the account.

class ScopeUnionMember1: …
type: Literal["sending_domain"]

Blocks the recipient only for mail whose envelope MAIL FROM uses value.

value: str

The sending domain: the domain part of the envelope MAIL FROM, lowercase, without a trailing dot.

maxLength1024
class SuppressionCreateResponse: …
id: str

The suppression’s identifier.

formatuuid
scope: Optional[Scope]

Where the suppression applies: account for every sending domain of the account, or sending_domain for one envelope MAIL FROM domain.

One of the following:
class ScopeType: …
type: Literal["account"]

Blocks the recipient for every sending domain of the account.

class ScopeUnionMember1: …
type: Literal["sending_domain"]

Blocks the recipient only for mail whose envelope MAIL FROM uses value.

value: str

The sending domain: the domain part of the envelope MAIL FROM, lowercase, without a trailing dot.

maxLength1024
class SuppressionEditResponse: …
id: str

Unique identifier for this suppression.

formatuuid
created_at: datetime

When the suppression was created.

formatdate-time
email: str

The suppressed email address.

formatemail
expires_at: Optional[datetime]

When the suppression expires. Null for a permanent suppression.

formatdate-time
read_only: bool

Whether clients may mutate this suppression. This is determined by the server and must not be inferred from reason.

reason: str

Why the address is suppressed: manual, complaint, hard_bounce, soft_bounce, or policy.

note: Optional[str]

Advisory note for this suppression, if any.

scope: Optional[Scope]

Where the suppression applies: account for every sending domain of the account, or sending_domain for one envelope MAIL FROM domain.

One of the following:
class ScopeType: …
type: Literal["account"]

Blocks the recipient for every sending domain of the account.

class ScopeUnionMember1: …
type: Literal["sending_domain"]

Blocks the recipient only for mail whose envelope MAIL FROM uses value.

value: str

The sending domain: the domain part of the envelope MAIL FROM, lowercase, without a trailing dot.

maxLength1024
class SuppressionDeleteResponse: …
id: str

The suppression’s identifier.

formatuuid
scope: Optional[Scope]

Where the suppression applies: account for every sending domain of the account, or sending_domain for one envelope MAIL FROM domain.

One of the following:
class ScopeType: …
type: Literal["account"]

Blocks the recipient for every sending domain of the account.

class ScopeUnionMember1: …
type: Literal["sending_domain"]

Blocks the recipient only for mail whose envelope MAIL FROM uses value.

value: str

The sending domain: the domain part of the envelope MAIL FROM, lowercase, without a trailing dot.

maxLength1024
class SuppressionImportResponse: …
deduplicated: int

Number of items dropped because their email address and scope repeated an earlier item in this request. Counted once and excluded from items.

errors: int

Number of items that failed to import due to an unexpected error.

invalid: int

Number of items with an invalid email address or sending domain.

items: List[Item]

Per-item results, in the same order as the request body.

index: int

Zero-based index of this item in the request body.

status: Literal["processed", "invalid", "error", "skipped"]

Outcome for this item.

One of the following:
"processed"
"invalid"
"error"
"skipped"
id: Optional[str]

The created or promoted suppression’s identifier. Present when status is processed.

formatuuid
email: Optional[str]

The submitted email address for this item.

formatemail
error: Optional[str]

Human-readable error message. Present when status is invalid, error, or skipped.

scope: Optional[ItemScope]

Where the suppression applies: account for every sending domain of the account, or sending_domain for one envelope MAIL FROM domain.

One of the following:
class ItemScopeType: …
type: Literal["account"]

Blocks the recipient for every sending domain of the account.

class ItemScopeUnionMember1: …
type: Literal["sending_domain"]

Blocks the recipient only for mail whose envelope MAIL FROM uses value.

value: str

The sending domain: the domain part of the envelope MAIL FROM, lowercase, without a trailing dot.

maxLength1024
processed: int

Number of items successfully created or promoted.

skipped: int

Number of items skipped because the existing suppression is not customer-managed (for example, a read-only policy suppression).

total: int

Total number of items in the request body, including duplicates.

Email SendingSubdomains

List sending subdomains
email_sending.subdomains.list(SubdomainListParams**kwargs) -> SyncSinglePage[SubdomainListResponse]
GET/zones/{zone_id}/email/sending/subdomains
Get a sending subdomain
email_sending.subdomains.get(strsubdomain_id, SubdomainGetParams**kwargs) -> SubdomainGetResponse
GET/zones/{zone_id}/email/sending/subdomains/{subdomain_id}
Create a sending subdomain
email_sending.subdomains.create(SubdomainCreateParams**kwargs) -> SubdomainCreateResponse
POST/zones/{zone_id}/email/sending/subdomains
Update a sending subdomain
email_sending.subdomains.edit(strsubdomain_id, SubdomainEditParams**kwargs) -> SubdomainEditResponse
PATCH/zones/{zone_id}/email/sending/subdomains/{subdomain_id}
Delete a sending subdomain
email_sending.subdomains.delete(strsubdomain_id, SubdomainDeleteParams**kwargs) -> SubdomainDeleteResponse
DELETE/zones/{zone_id}/email/sending/subdomains/{subdomain_id}
ModelsExpand Collapse
class SubdomainListResponse: …
enabled: bool

Whether Email Sending is enabled on this subdomain.

name: str

The exact domain name or a leftmost wildcard such as *.example.com.

tag: str

Sending subdomain identifier.

maxLength32
created: Optional[datetime]

The date and time the destination address has been created.

formatdate-time
dkim_selector: Optional[str]

The DKIM selector used for email signing. Wildcard rows publish the selector and sign with d=<base>.

drop_suppressed_recipients: Optional[bool]

Whether a send request that includes a recipient suppressed on this subdomain drops that recipient and still delivers to the rest, instead of failing the entire request.

modified: Optional[datetime]

The date and time the destination address was last modified.

formatdate-time
preview_enabled: Optional[bool]

Whether sent messages from this subdomain can be previewed in the activity log.

return_path_domain: Optional[str]

The return-path domain used for bounce handling. Wildcard rows use cf-bounce.<base>.

class SubdomainGetResponse: …
enabled: bool

Whether Email Sending is enabled on this subdomain.

name: str

The exact domain name or a leftmost wildcard such as *.example.com.

tag: str

Sending subdomain identifier.

maxLength32
created: Optional[datetime]

The date and time the destination address has been created.

formatdate-time
dkim_selector: Optional[str]

The DKIM selector used for email signing. Wildcard rows publish the selector and sign with d=<base>.

drop_suppressed_recipients: Optional[bool]

Whether a send request that includes a recipient suppressed on this subdomain drops that recipient and still delivers to the rest, instead of failing the entire request.

modified: Optional[datetime]

The date and time the destination address was last modified.

formatdate-time
preview_enabled: Optional[bool]

Whether sent messages from this subdomain can be previewed in the activity log.

return_path_domain: Optional[str]

The return-path domain used for bounce handling. Wildcard rows use cf-bounce.<base>.

class SubdomainCreateResponse: …
enabled: bool

Whether Email Sending is enabled on this subdomain.

name: str

The exact domain name or a leftmost wildcard such as *.example.com.

tag: str

Sending subdomain identifier.

maxLength32
created: Optional[datetime]

The date and time the destination address has been created.

formatdate-time
dkim_selector: Optional[str]

The DKIM selector used for email signing. Wildcard rows publish the selector and sign with d=<base>.

drop_suppressed_recipients: Optional[bool]

Whether a send request that includes a recipient suppressed on this subdomain drops that recipient and still delivers to the rest, instead of failing the entire request.

modified: Optional[datetime]

The date and time the destination address was last modified.

formatdate-time
preview_enabled: Optional[bool]

Whether sent messages from this subdomain can be previewed in the activity log.

return_path_domain: Optional[str]

The return-path domain used for bounce handling. Wildcard rows use cf-bounce.<base>.

class SubdomainEditResponse: …
enabled: bool

Whether Email Sending is enabled on this subdomain.

name: str

The exact domain name or a leftmost wildcard such as *.example.com.

tag: str

Sending subdomain identifier.

maxLength32
created: Optional[datetime]

The date and time the destination address has been created.

formatdate-time
dkim_selector: Optional[str]

The DKIM selector used for email signing. Wildcard rows publish the selector and sign with d=<base>.

drop_suppressed_recipients: Optional[bool]

Whether a send request that includes a recipient suppressed on this subdomain drops that recipient and still delivers to the rest, instead of failing the entire request.

modified: Optional[datetime]

The date and time the destination address was last modified.

formatdate-time
preview_enabled: Optional[bool]

Whether sent messages from this subdomain can be previewed in the activity log.

return_path_domain: Optional[str]

The return-path domain used for bounce handling. Wildcard rows use cf-bounce.<base>.

class SubdomainDeleteResponse: …
errors: List[Error]
code: int
minimum1000
message: str
documentation_url: Optional[str]
source: Optional[ErrorSource]
pointer: Optional[str]
messages: List[Message]
code: int
minimum1000
message: str
documentation_url: Optional[str]
source: Optional[MessageSource]
pointer: Optional[str]
success: Literal[true]

Whether the API call was successful.

Email SendingSubdomainsDNS

Get sending subdomain DNS records
email_sending.subdomains.dns.get(strsubdomain_id, DNSGetParams**kwargs) -> SyncSinglePage[DNSRecord]
GET/zones/{zone_id}/email/sending/subdomains/{subdomain_id}/dns