# Email Sending

## Send an email

`email_sending.send(EmailSendingSendParams**kwargs)  -> EmailSendingSendResponse`

**post** `/accounts/{account_id}/email/sending/send`

Send an email for the specified account using the structured builder. Provide the sender, recipients, subject, and at least one of text or html; attachments are optional.

### 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: Optional[str]`

      Display name for the email address (e.g., 'John Doe'). Optional; set to null or leave it unset to send the address on its own.

- `subject: str`

  Email subject line.

- `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., <img src="cid:logo">).

    - `disposition: Literal["inline"]`

      Must be 'inline'. Embeds the attachment 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'. Adds 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[Bcc]`

  BCC recipient(s). A single email string, a named address object, or an array of either.

  - `str`

    An email address as a plain string.

  - `class BccEmailSendingEmailAddressObject: …`

    - `address: str`

      Email address (e.g., 'user@example.com').

    - `name: Optional[str]`

      Display name for the email address (e.g., 'John Doe'). Optional; set to null or leave it unset to send the address on its own.

  - `Sequence[BccUnionMember2]`

    - `str`

      An email address as a plain string.

    - `class BccUnionMember2EmailSendingEmailAddressObject: …`

      - `address: str`

        Email address (e.g., 'user@example.com').

      - `name: Optional[str]`

        Display name for the email address (e.g., 'John Doe'). Optional; set to null or leave it unset to send the address on its own.

- `cc: Optional[Cc]`

  CC recipient(s). A single email string, a named address object, or an array of either.

  - `str`

    An email address as a plain string.

  - `class CcEmailSendingEmailAddressObject: …`

    - `address: str`

      Email address (e.g., 'user@example.com').

    - `name: Optional[str]`

      Display name for the email address (e.g., 'John Doe'). Optional; set to null or leave it unset to send the address on its own.

  - `Sequence[CcUnionMember2]`

    - `str`

      An email address as a plain string.

    - `class CcUnionMember2EmailSendingEmailAddressObject: …`

      - `address: str`

        Email address (e.g., 'user@example.com').

      - `name: Optional[str]`

        Display name for the email address (e.g., 'John Doe'). Optional; set to null or leave it unset to send the address on its own.

- `headers: Optional[Dict[str, str]]`

  Custom email headers as key-value pairs.

- `html: Optional[str]`

  HTML body of the email. Provide at least one of text or html (non-empty).

- `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: Optional[str]`

      Display name for the email address (e.g., 'John Doe'). Optional; set to null or leave it unset to send the address on its own.

- `text: Optional[str]`

  Plain text body of the email. Provide at least one of text or html (non-empty).

- `to: Optional[To]`

  Recipient(s). Optional if cc or bcc is provided. A single email string, a named address object, or an array of either.

  - `str`

    An email address as a plain string.

  - `class ToEmailSendingEmailAddressObject: …`

    - `address: str`

      Email address (e.g., 'user@example.com').

    - `name: Optional[str]`

      Display name for the email address (e.g., 'John Doe'). Optional; set to null or leave it unset to send the address on its own.

  - `Sequence[ToUnionMember2]`

    - `str`

      An email address as a plain string.

    - `class ToUnionMember2EmailSendingEmailAddressObject: …`

      - `address: str`

        Email address (e.g., 'user@example.com').

      - `name: Optional[str]`

        Display name for the email address (e.g., 'John Doe'). Optional; set to null or leave it unset to send the address on its own.

### Returns

- `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.

### 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",
)
print(response.message_id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "delivered": [
      "recipient@example.com"
    ],
    "message_id": "<aB3xK9mP2qR5sT8uV0wX1yZ4cD6fG7hJ9kL0@example.com>",
    "permanent_bounces": [
      "string"
    ],
    "queued": [
      "string"
    ]
  },
  "success": true,
  "result_info": {
    "count": 0,
    "per_page": 0,
    "total_count": 0,
    "cursor": "cursor",
    "page": 0
  }
}
```

## Send a raw MIME email

`email_sending.send_raw(EmailSendingSendRawParams**kwargs)  -> EmailSendingSendRawResponse`

**post** `/accounts/{account_id}/email/sending/send_raw`

Send a raw RFC 5322 (MIME) email for the specified account. Provide the full MIME message plus the SMTP envelope (from and recipients).

### 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: Sequence[str]`

  List of recipient email addresses.

### Returns

- `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.

### 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.message_id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "delivered": [
      "recipient@example.com"
    ],
    "message_id": "<aB3xK9mP2qR5sT8uV0wX1yZ4cD6fG7hJ9kL0@example.com>",
    "permanent_bounces": [
      "string"
    ],
    "queued": [
      "string"
    ]
  },
  "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.

  - `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.

### Email Sending Send Raw Response

- `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.

# 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: …`

  - `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.

  - `dkim_selector: Optional[str]`

    The DKIM selector used for email signing.

  - `modified: Optional[datetime]`

    The date and time the destination address was last modified.

  - `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.

### 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.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": [
    {
      "enabled": true,
      "name": "sub.example.com",
      "tag": "aabbccdd11223344aabbccdd11223344",
      "created": "2014-01-02T02:20:00Z",
      "dkim_selector": "cf-bounce",
      "modified": "2014-01-02T02:20:00Z",
      "preview_enabled": true,
      "return_path_domain": "cf-bounce.sub.example.com"
    }
  ],
  "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: …`

  - `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.

  - `dkim_selector: Optional[str]`

    The DKIM selector used for email signing.

  - `modified: Optional[datetime]`

    The date and time the destination address was last modified.

  - `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.

### 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.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": {
    "enabled": true,
    "name": "sub.example.com",
    "tag": "aabbccdd11223344aabbccdd11223344",
    "created": "2014-01-02T02:20:00Z",
    "dkim_selector": "cf-bounce",
    "modified": "2014-01-02T02:20:00Z",
    "preview_enabled": true,
    "return_path_domain": "cf-bounce.sub.example.com"
  }
}
```

## 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: …`

  - `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.

  - `dkim_selector: Optional[str]`

    The DKIM selector used for email signing.

  - `modified: Optional[datetime]`

    The date and time the destination address was last modified.

  - `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.

### 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.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": {
    "enabled": true,
    "name": "sub.example.com",
    "tag": "aabbccdd11223344aabbccdd11223344",
    "created": "2014-01-02T02:20:00Z",
    "dkim_selector": "cf-bounce",
    "modified": "2014-01-02T02:20:00Z",
    "preview_enabled": true,
    "return_path_domain": "cf-bounce.sub.example.com"
  }
}
```

## 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: …`

  - `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.

  - `dkim_selector: Optional[str]`

    The DKIM selector used for email signing.

  - `modified: Optional[datetime]`

    The date and time the destination address was last modified.

  - `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.

### Subdomain Get Response

- `class SubdomainGetResponse: …`

  - `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.

  - `dkim_selector: Optional[str]`

    The DKIM selector used for email signing.

  - `modified: Optional[datetime]`

    The date and time the destination address was last modified.

  - `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.

### Subdomain Create Response

- `class SubdomainCreateResponse: …`

  - `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.

  - `dkim_selector: Optional[str]`

    The DKIM selector used for email signing.

  - `modified: Optional[datetime]`

    The date and time the destination address was last modified.

  - `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.

### 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
  }
}
```