# Email Sending ## Send an email using the builder. `email_sending.send(EmailSendingSendParams**kwargs) -> EmailSendingSendResponse` **post** `/accounts/{account_id}/email/sending/send` Send an email using the builder. ### Parameters - `account_id: str` Identifier of the account. - `from_: From` Sender email address. Either a plain string or an object with address and name. - `str` An email address as a plain string. - `class FromEmailSendingEmailAddressObject: …` - `address: str` Email address (e.g., 'user@example.com'). - `name: str` Display name for the email address (e.g., 'John Doe'). - `subject: str` Email subject line. - `to: Union[str, SequenceNotStr[str]]` Recipient(s). A single email string or an array of email strings. - `str` An email address as a plain string. - `SequenceNotStr[str]` A list of email address strings. - `attachments: Optional[Iterable[Attachment]]` File attachments and inline images. - `class AttachmentEmailSendingEmailInlineAttachment: …` - `content: str` Base64-encoded content of the attachment. - `content_id: str` Content ID used to reference this attachment in HTML via cid: URI (e.g., ). - `disposition: Literal["inline"]` Must be 'inline'. Indicates the attachment is embedded in the email body. - `"inline"` - `filename: str` Filename for the attachment. - `type: str` MIME type of the attachment (e.g., 'image/png', 'text/plain'). - `class AttachmentEmailSendingEmailAttachment: …` - `content: str` Base64-encoded content of the attachment. - `disposition: Literal["attachment"]` Must be 'attachment'. Indicates a standard file attachment. - `"attachment"` - `filename: str` Filename for the attachment. - `type: str` MIME type of the attachment (e.g., 'application/pdf', 'text/plain'). - `bcc: Optional[Union[str, SequenceNotStr[str]]]` BCC recipient(s). A single email string or an array of email strings. - `str` An email address as a plain string. - `SequenceNotStr[str]` A list of email address strings. - `cc: Optional[Union[str, SequenceNotStr[str]]]` CC recipient(s). A single email string or an array of email strings. - `str` An email address as a plain string. - `SequenceNotStr[str]` A list of email address strings. - `headers: Optional[Dict[str, str]]` Custom email headers as key-value pairs. - `html: Optional[str]` HTML body of the email. At least one of text or html must be provided. - `reply_to: Optional[ReplyTo]` Reply-to address. Either a plain string or an object with address and name. - `str` An email address as a plain string. - `class ReplyToEmailSendingEmailAddressObject: …` - `address: str` Email address (e.g., 'user@example.com'). - `name: str` Display name for the email address (e.g., 'John Doe'). - `text: Optional[str]` Plain text body of the email. At least one of text or html must be provided. ### Returns - `class EmailSendingSendResponse: …` - `delivered: List[str]` Email addresses to which the message was delivered immediately. - `permanent_bounces: List[str]` Email addresses that permanently bounced. - `queued: List[str]` Email addresses for which delivery was queued for later. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.email_sending.send( account_id="account_id", from_="sender@example.com", subject="Monthly Report", to=["recipient@example.com"], ) print(response.delivered) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "result": { "delivered": [ "recipient@example.com" ], "permanent_bounces": [ "dev@stainless.com" ], "queued": [ "dev@stainless.com" ] }, "success": true, "result_info": { "count": 0, "per_page": 0, "total_count": 0, "cursor": "cursor", "page": 0 } } ``` ## Send a raw MIME email message. `email_sending.send_raw(EmailSendingSendRawParams**kwargs) -> EmailSendingSendRawResponse` **post** `/accounts/{account_id}/email/sending/send_raw` Send a raw MIME email message. ### Parameters - `account_id: str` Identifier of the account. - `from_: str` Sender email address. - `mime_message: str` The full MIME-encoded email message. Should include standard RFC 5322 headers such as From, To, Subject, and Content-Type. The from and recipients fields in the request body control SMTP envelope routing; the From and To headers in the MIME message control what the recipient's email client displays. - `recipients: SequenceNotStr[str]` List of recipient email addresses. ### Returns - `class EmailSendingSendRawResponse: …` - `delivered: List[str]` Email addresses to which the message was delivered immediately. - `permanent_bounces: List[str]` Email addresses that permanently bounced. - `queued: List[str]` Email addresses for which delivery was queued for later. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) response = client.email_sending.send_raw( account_id="account_id", from_="sender@example.com", mime_message="From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Hello\r\nContent-Type: text/plain\r\n\r\nHello, World!", recipients=["recipient@example.com"], ) print(response.delivered) ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "result": { "delivered": [ "recipient@example.com" ], "permanent_bounces": [ "dev@stainless.com" ], "queued": [ "dev@stainless.com" ] }, "success": true, "result_info": { "count": 0, "per_page": 0, "total_count": 0, "cursor": "cursor", "page": 0 } } ``` ## Domain Types ### Email Sending Send Response - `class EmailSendingSendResponse: …` - `delivered: List[str]` Email addresses to which the message was delivered immediately. - `permanent_bounces: List[str]` Email addresses that permanently bounced. - `queued: List[str]` Email addresses for which delivery was queued for later. ### Email Sending Send Raw Response - `class EmailSendingSendRawResponse: …` - `delivered: List[str]` Email addresses to which the message was delivered immediately. - `permanent_bounces: List[str]` Email addresses that permanently bounced. - `queued: List[str]` Email addresses for which delivery was queued for later. # Subdomains ## List sending subdomains `email_sending.subdomains.list(SubdomainListParams**kwargs) -> SyncSinglePage[SubdomainListResponse]` **get** `/zones/{zone_id}/email/sending/subdomains` Lists all sending-enabled subdomains for the zone. ### Parameters - `zone_id: str` Identifier. ### Returns - `class SubdomainListResponse: …` - `email_sending_enabled: bool` Whether Email Sending is enabled on this subdomain. - `name: str` The subdomain domain name. - `tag: str` Sending subdomain identifier. - `created: Optional[datetime]` The date and time the destination address has been created. - `email_sending_dkim_selector: Optional[str]` The DKIM selector used for email signing. - `email_sending_return_path_domain: Optional[str]` The return-path domain used for bounce handling. - `enabled: Optional[bool]` Whether Email Routing (receiving) is enabled on this subdomain. Read-only; included for informational purposes since both services share the subdomain row. - `modified: Optional[datetime]` The date and time the destination address was last modified. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted ) page = client.email_sending.subdomains.list( zone_id="023e105f4ecef8ad9ca31a8372d0c353", ) page = page.result[0] print(page.email_sending_enabled) ``` #### Response ```json { "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": [ { "email_sending_enabled": true, "name": "sub.example.com", "tag": "aabbccdd11223344aabbccdd11223344", "created": "2014-01-02T02:20:00Z", "email_sending_dkim_selector": "cf-bounce", "email_sending_return_path_domain": "cf-bounce.sub.example.com", "enabled": true, "modified": "2014-01-02T02:20:00Z" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Get a sending subdomain `email_sending.subdomains.get(strsubdomain_id, SubdomainGetParams**kwargs) -> SubdomainGetResponse` **get** `/zones/{zone_id}/email/sending/subdomains/{subdomain_id}` Gets information for a specific sending subdomain. ### Parameters - `zone_id: str` Identifier. - `subdomain_id: str` Sending subdomain identifier. ### Returns - `class SubdomainGetResponse: …` - `email_sending_enabled: bool` Whether Email Sending is enabled on this subdomain. - `name: str` The subdomain domain name. - `tag: str` Sending subdomain identifier. - `created: Optional[datetime]` The date and time the destination address has been created. - `email_sending_dkim_selector: Optional[str]` The DKIM selector used for email signing. - `email_sending_return_path_domain: Optional[str]` The return-path domain used for bounce handling. - `enabled: Optional[bool]` Whether Email Routing (receiving) is enabled on this subdomain. Read-only; included for informational purposes since both services share the subdomain row. - `modified: Optional[datetime]` The date and time the destination address was last modified. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted ) subdomain = client.email_sending.subdomains.get( subdomain_id="aabbccdd11223344aabbccdd11223344", zone_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(subdomain.email_sending_enabled) ``` #### Response ```json { "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": { "email_sending_enabled": true, "name": "sub.example.com", "tag": "aabbccdd11223344aabbccdd11223344", "created": "2014-01-02T02:20:00Z", "email_sending_dkim_selector": "cf-bounce", "email_sending_return_path_domain": "cf-bounce.sub.example.com", "enabled": true, "modified": "2014-01-02T02:20:00Z" } } ``` ## Create a sending subdomain `email_sending.subdomains.create(SubdomainCreateParams**kwargs) -> SubdomainCreateResponse` **post** `/zones/{zone_id}/email/sending/subdomains` 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. ### Parameters - `zone_id: str` Identifier. - `name: str` The subdomain name. Must be within the zone. ### Returns - `class SubdomainCreateResponse: …` - `email_sending_enabled: bool` Whether Email Sending is enabled on this subdomain. - `name: str` The subdomain domain name. - `tag: str` Sending subdomain identifier. - `created: Optional[datetime]` The date and time the destination address has been created. - `email_sending_dkim_selector: Optional[str]` The DKIM selector used for email signing. - `email_sending_return_path_domain: Optional[str]` The return-path domain used for bounce handling. - `enabled: Optional[bool]` Whether Email Routing (receiving) is enabled on this subdomain. Read-only; included for informational purposes since both services share the subdomain row. - `modified: Optional[datetime]` The date and time the destination address was last modified. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted ) subdomain = client.email_sending.subdomains.create( zone_id="023e105f4ecef8ad9ca31a8372d0c353", name="sub.example.com", ) print(subdomain.email_sending_enabled) ``` #### Response ```json { "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": { "email_sending_enabled": true, "name": "sub.example.com", "tag": "aabbccdd11223344aabbccdd11223344", "created": "2014-01-02T02:20:00Z", "email_sending_dkim_selector": "cf-bounce", "email_sending_return_path_domain": "cf-bounce.sub.example.com", "enabled": true, "modified": "2014-01-02T02:20:00Z" } } ``` ## Delete a sending subdomain `email_sending.subdomains.delete(strsubdomain_id, SubdomainDeleteParams**kwargs) -> SubdomainDeleteResponse` **delete** `/zones/{zone_id}/email/sending/subdomains/{subdomain_id}` Disables sending on a subdomain and removes its DNS records. If routing is still active on the subdomain, only sending is disabled. ### Parameters - `zone_id: str` Identifier. - `subdomain_id: str` Sending subdomain identifier. ### Returns - `class SubdomainDeleteResponse: …` - `errors: List[Error]` - `code: int` - `message: str` - `documentation_url: Optional[str]` - `source: Optional[ErrorSource]` - `pointer: Optional[str]` - `messages: List[Message]` - `code: int` - `message: str` - `documentation_url: Optional[str]` - `source: Optional[MessageSource]` - `pointer: Optional[str]` - `success: Literal[true]` Whether the API call was successful. - `true` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted ) subdomain = client.email_sending.subdomains.delete( subdomain_id="aabbccdd11223344aabbccdd11223344", zone_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(subdomain.errors) ``` #### Response ```json { "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 } ``` ## Domain Types ### Subdomain List Response - `class SubdomainListResponse: …` - `email_sending_enabled: bool` Whether Email Sending is enabled on this subdomain. - `name: str` The subdomain domain name. - `tag: str` Sending subdomain identifier. - `created: Optional[datetime]` The date and time the destination address has been created. - `email_sending_dkim_selector: Optional[str]` The DKIM selector used for email signing. - `email_sending_return_path_domain: Optional[str]` The return-path domain used for bounce handling. - `enabled: Optional[bool]` Whether Email Routing (receiving) is enabled on this subdomain. Read-only; included for informational purposes since both services share the subdomain row. - `modified: Optional[datetime]` The date and time the destination address was last modified. ### Subdomain Get Response - `class SubdomainGetResponse: …` - `email_sending_enabled: bool` Whether Email Sending is enabled on this subdomain. - `name: str` The subdomain domain name. - `tag: str` Sending subdomain identifier. - `created: Optional[datetime]` The date and time the destination address has been created. - `email_sending_dkim_selector: Optional[str]` The DKIM selector used for email signing. - `email_sending_return_path_domain: Optional[str]` The return-path domain used for bounce handling. - `enabled: Optional[bool]` Whether Email Routing (receiving) is enabled on this subdomain. Read-only; included for informational purposes since both services share the subdomain row. - `modified: Optional[datetime]` The date and time the destination address was last modified. ### Subdomain Create Response - `class SubdomainCreateResponse: …` - `email_sending_enabled: bool` Whether Email Sending is enabled on this subdomain. - `name: str` The subdomain domain name. - `tag: str` Sending subdomain identifier. - `created: Optional[datetime]` The date and time the destination address has been created. - `email_sending_dkim_selector: Optional[str]` The DKIM selector used for email signing. - `email_sending_return_path_domain: Optional[str]` The return-path domain used for bounce handling. - `enabled: Optional[bool]` Whether Email Routing (receiving) is enabled on this subdomain. Read-only; included for informational purposes since both services share the subdomain row. - `modified: Optional[datetime]` The date and time the destination address was last modified. ### Subdomain Delete Response - `class SubdomainDeleteResponse: …` - `errors: List[Error]` - `code: int` - `message: str` - `documentation_url: Optional[str]` - `source: Optional[ErrorSource]` - `pointer: Optional[str]` - `messages: List[Message]` - `code: int` - `message: str` - `documentation_url: Optional[str]` - `source: Optional[MessageSource]` - `pointer: Optional[str]` - `success: Literal[true]` Whether the API call was successful. - `true` # DNS ## 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` Returns the expected DNS records for a sending subdomain. ### Parameters - `zone_id: str` Identifier. - `subdomain_id: str` Sending subdomain identifier. ### Returns - `class DNSRecord: …` List of records needed to enable an Email Routing zone. - `content: Optional[str]` DNS record content. - `name: Optional[str]` DNS record name (or @ for the zone apex). - `priority: Optional[float]` Required for MX, SRV and URI records. Unused by other record types. Records with lower priorities are preferred. - `ttl: Optional[Union[float, Literal[1], null]]` Time to live, in seconds, of the DNS record. Must be between 60 and 86400, or 1 for 'automatic'. - `float` - `Literal[1]` Time to live, in seconds, of the DNS record. Must be between 60 and 86400, or 1 for 'automatic'. - `1` - `type: Optional[Literal["A", "AAAA", "CNAME", 15 more]]` DNS record type. - `"A"` - `"AAAA"` - `"CNAME"` - `"HTTPS"` - `"TXT"` - `"SRV"` - `"LOC"` - `"MX"` - `"NS"` - `"CERT"` - `"DNSKEY"` - `"DS"` - `"NAPTR"` - `"SMIMEA"` - `"SSHFP"` - `"SVCB"` - `"TLSA"` - `"URI"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted ) page = client.email_sending.subdomains.dns.get( subdomain_id="aabbccdd11223344aabbccdd11223344", zone_id="023e105f4ecef8ad9ca31a8372d0c353", ) page = page.result[0] print(page.content) ``` #### Response ```json { "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": [ { "content": "route1.mx.cloudflare.net", "name": "example.com", "priority": 12, "ttl": 1, "type": "NS" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ```