Send an email using the builder.

email_sending.send() -> EmailSendingSendResponse

POST/accounts/{account_id}/email/sending/send

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

ParametersExpand Collapse

account_id: str

Identifier of the account.

from_: From

Sender email address. Either a plain string or an object with address and name.

One of the following:

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.

One of the following:

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.

One of the following:

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.

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.

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.

One of the following:

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.

One of the following:

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.

One of the following:

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.

ReturnsExpand Collapse

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.

Send an email using the builder.

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)

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

Returns Examples

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