Cloudflare.Email reference

Address

Source: src/Cloudflare/Email/Address.ts

A verified destination email address on the account.

Destination addresses are account-scoped (not zone-scoped). They are used as forwarding targets in Rule actions and can also serve as the destinationAddress on a send_email Worker binding.

Address: Registering an Address

const ops = yield* Cloudflare.Email.Address("Ops", {
  email: "ops@example.com",
});

Cloudflare sends a verification email when the address is first created. The address must be verified before it can receive routed mail.

AllowPolicy

Source: src/Cloudflare/Email/AllowPolicy.ts

A Cloudflare Email Security (Area 1) allow policy — exempts messages matching a sender/recipient pattern from detections.

All fields are mutable in place. Requires the Email Security enterprise add-on; accounts without the entitlement receive the typed EmailSecurityNotEntitled error.

AllowPolicy: Creating an Allow Policy

Acceptable sender by email address

yield* Cloudflare.Email.AllowPolicy("NewsletterSender", {
  pattern: "news@partner.example.com",
  patternType: "EMAIL",
  isAcceptableSender: true,
});

Trusted sender domain (bypasses all detections)

yield* Cloudflare.Email.AllowPolicy("TrustedPartner", {
  pattern: "partner.example.com",
  patternType: "DOMAIN",
  isTrustedSender: true,
  comments: "contractually trusted partner",
});

Exempt recipient

// Messages delivered to the abuse mailbox must never be filtered.
yield* Cloudflare.Email.AllowPolicy("AbuseMailbox", {
  pattern: "abuse@example.com",
  patternType: "EMAIL",
  isExemptRecipient: true,
  verifySender: false,
});

BlockSender

Source: src/Cloudflare/Email/BlockSender.ts

A Cloudflare Email Security (Area 1) blocked sender — messages matching the pattern are blocked before delivery.

All fields are mutable in place. Requires the Email Security enterprise add-on; accounts without the entitlement receive the typed EmailSecurityNotEntitled error.

BlockSender: Blocking Senders

Block a single email address

yield* Cloudflare.Email.BlockSender("KnownPhisher", {
  pattern: "phisher@malicious.example.com",
  patternType: "EMAIL",
  comments: "reported in incident 1234",
});

Block a whole sending domain

yield* Cloudflare.Email.BlockSender("SpamDomain", {
  pattern: "spam-source.example.net",
  patternType: "DOMAIN",
});

Block by regular expression

yield* Cloudflare.Email.BlockSender("LookalikeSenders", {
  pattern: ".*@examp1e\\.com$",
  patternType: "EMAIL",
  isRegex: true,
});

CatchAll

Source: src/Cloudflare/Email/CatchAll.ts

The Cloudflare Email Routing catch-all rule for a zone.

The catch-all rule handles every inbound email that no other routing rule matched. It is a per-zone singleton — once Email Routing is enabled the rule always exists (disabled, dropping mail, by default), so this resource never creates or deletes anything physical. Reconcile PUTs the desired configuration; destroy restores the configuration the rule had before Alchemy first managed it.

Email Routing must be enabled on the zone first (see Cloudflare.Email.Routing), and forward actions require the destination address to be verified (see Cloudflare.Email.Address).

CatchAll: Catching unmatched mail

Forward everything else to a verified destination

const routing = yield* Cloudflare.Email.Routing("Routing", {
  zone: "example.com",
});

yield* Cloudflare.Email.CatchAll("CatchAll", {
  zone: routing.zoneId,
  actions: [{ type: "forward", value: ["ops@example.com"] }],
});

Silently drop unmatched mail

yield* Cloudflare.Email.CatchAll("DropTheRest", {
  zone: routing.zoneId,
  name: "drop unmatched",
  actions: [{ type: "drop" }],
});

CatchAll: Workers

yield* Cloudflare.Email.CatchAll("CatchAllWorker", {
  zone: routing.zoneId,
  actions: [{ type: "worker", value: ["my-email-worker"] }],
});

Domain

Source: src/Cloudflare/Email/Domain.ts

A Cloudflare Email Security (Area 1) domain’s settings.

Domains cannot be created via the API — they appear when the domain is onboarded to Email Security (MX/BCC/journal or an API integration) in the dashboard. This resource adopts and configures an existing domain: read finds it by name and reports it as unowned, so taking it under management is gated behind --adopt (or adopt(true)).

Destroying this resource offboards the domain from Email Security (the underlying API call is DELETE .../settings/domains/{id}). Mail flow for the domain is no longer scanned afterwards. Plan destroys with care.

Requires the Email Security enterprise add-on; accounts without the entitlement receive the typed EmailSecurityNotEntitled error.

Domain: Configuring a Domain

Drop malicious mail before delivery

yield* Cloudflare.Email.Domain("MailDomain", {
  domain: "example.com",
  dropDispositions: ["MALICIOUS", "SPOOF"],
});

Restrict inbound delivery and require TLS

yield* Cloudflare.Email.Domain("MailDomain", {
  domain: "example.com",
  ipRestrictions: ["203.0.113.0/24"],
  requireTlsInbound: true,
  requireTlsOutbound: true,
  transport: "mx.example.com",
});

ImpersonationRegistryEntry

Source: src/Cloudflare/Email/ImpersonationRegistryEntry.ts

A Cloudflare Email Security (Area 1) impersonation registry entry — maps a protected display name (e.g. a VIP) to their legitimate email address for BEC/impersonation detection.

All fields are mutable in place. Directory-synced fields (directory_id, directory_node_id, provenance) are managed by Office365/Google integrations and are not exposed as inputs. Requires the Email Security enterprise add-on; accounts without the entitlement receive the typed EmailSecurityNotEntitled error.

ImpersonationRegistryEntry: Registering Protected Identities

Protect an executive’s display name

yield* Cloudflare.Email.ImpersonationRegistryEntry("Ceo", {
  name: "Jane Smith",
  email: "jane.smith@example.com",
  comments: "CEO — high-value BEC target",
});

Match several legitimate addresses with a regex

yield* Cloudflare.Email.ImpersonationRegistryEntry("Finance", {
  name: "Accounts Payable",
  email: "^ap(-[a-z]+)?@example\\.com$",
  isEmailRegex: true,
});

Routing

Source: src/Cloudflare/Email/Routing.ts

Enables Cloudflare Email Routing on a zone. This is the prerequisite for receiving mail at any address on the domain and for sending email from a Worker via send_email bindings.

Routing: Enabling Email Routing

const routing = yield* Cloudflare.Email.Routing("Routing", {
  zone: "example.com",
});

Rule

Source: src/Cloudflare/Email/Rule.ts

A Cloudflare Email Routing rule.

Rules forward inbound mail matching matchers to the listed actions (forward to a verified destination, drop, or hand off to a Worker).

Rule: Forwarding Mail

const rule = yield* Cloudflare.Email.Rule("InfoForward", {
  zone: "example.com",
  matchers: [{ type: "literal", field: "to", value: "info@example.com" }],
  actions: [{ type: "forward", value: ["ops@example.com"] }],
});

Send

Source: src/Cloudflare/Email/Send.ts

Bind a SendEmail send_email descriptor to a Worker and obtain the Effect-native client for sending email.

Send is a single identifier that is simultaneously the binding’s Context tag, its type, and the callable — yield* Cloudflare.Email.Send(EmailDescriptor).

Send: Examples

const Email = Cloudflare.Email.SendEmail("Email");

// in the Worker effect:
const email = yield* Cloudflare.Email.Send(Email);
yield* email.send({
  from: "noreply@example.com",
  to: "user@example.com",
  subject: "Hello",
  text: "Hi from Alchemy",
});

SendingSubdomain

Source: src/Cloudflare/Email/SendingSubdomain.ts

Registers a Cloudflare Email Sending subdomain on a zone, enabling the account to send transactional email from addresses on that subdomain.

Creating the subdomain provisions DKIM, SPF, and return-path configuration; for zones on Cloudflare DNS the required DNS records are created automatically and enabled flips to true once they validate (usually immediately).

The resource is existence-only: the API offers create, get, list, and delete but no update, so changing name or zoneId triggers a replacement.

Safety: sending subdomains carry no ownership markers. When there is no prior state, read scans the zone for an existing subdomain with the same name and reports it as Unowned, so the engine refuses to take it over unless --adopt (or adopt(true)) is set.

SendingSubdomain: Registering a sending subdomain

const sending = yield* Cloudflare.Email.SendingSubdomain("Mail", {
  zoneId: zone.zoneId,
  name: "mail.example.com",
});
// sending.enabled — true once DNS records validated
// sending.dkimSelector / sending.returnPathDomain — provisioned config

SendingSubdomain: Externally-hosted zones

import * as emailSending from "@distilled.cloud/cloudflare/email-sending";

// For zones not on Cloudflare DNS, fetch the expected records and add
// them at your DNS host; `enabled` flips to true once they validate.
const records = yield* emailSending.getSubdomainDns.items({
  zoneId: sending.zoneId,
  subdomainId: sending.subdomainId,
}).pipe(Stream.runCollect);

TrustedDomain

Source: src/Cloudflare/Email/TrustedDomain.ts

A Cloudflare Email Security (Area 1) trusted domain — exempts a domain from recently-registered and lookalike (similarity) detections.

All fields are mutable in place. Requires the Email Security enterprise add-on; accounts without the entitlement receive the typed EmailSecurityNotEntitled error.

TrustedDomain: Trusting Domains

Trust a partner domain with similar spelling

yield* Cloudflare.Email.TrustedDomain("PartnerLookalike", {
  pattern: "examp1e-partner.com",
  isSimilarity: true,
  comments: "legitimate partner domain",
});

Trust a recently registered domain

yield* Cloudflare.Email.TrustedDomain("NewSubsidiary", {
  pattern: "brand-new-subsidiary.example",
  isRecent: true,
});