import * as emailSending from "@distilled.cloud/cloudflare/email-sending";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";
const SendingSubdomainTypeId = "Cloudflare.Email.SendingSubdomain" as const;
type SendingSubdomainTypeId = typeof SendingSubdomainTypeId;
export interface SendingSubdomainProps {
/**
* Zone the sending subdomain is registered on. The subdomain name must
* be within this zone.
*
* Stable — moving the subdomain to another zone triggers a replacement.
*/
zoneId: string;
/**
* The fully-qualified subdomain to send email from (e.g.
* `mail.example.com`). Must be within the zone.
*
* Stable — the Cloudflare API has no update operation for sending
* subdomains, so a rename is a delete + create. Declared as plain
* `string` (not `string`) so it is statically knowable in `diff`.
*/
name: string;
/**
* Whether Cloudflare keeps a preview of each sent message in the activity
* log (retained for about seven days). Subdomains onboarded on or after
* 2026-07-02 start with previews on. Omit to leave the setting as
* Cloudflare has it.
*
* @see https://developers.cloudflare.com/email-service/observability/logs/#message-preview
*/
previewEnabled?: boolean;
}
export interface SendingSubdomainAttributes {
/** Cloudflare-assigned identifier of the sending subdomain. */
subdomainId: string;
/** Zone the sending subdomain is registered on. */
zoneId: string;
/** The subdomain domain name. */
name: string;
/**
* Whether Email Sending is enabled on this subdomain. Flips to `true`
* once the auto-provisioned DNS records (DKIM/SPF/return-path) validate
* — usually immediate for zones on Cloudflare DNS.
*/
enabled: boolean;
/** The DKIM selector used for email signing. */
dkimSelector: string | undefined;
/** The return-path domain used for bounce handling. */
returnPathDomain: string | undefined;
/** Whether sent messages can be previewed in the activity log. */
previewEnabled: boolean | undefined;
/** ISO8601 creation timestamp. */
created: string | undefined;
/** ISO8601 last-modified timestamp. */
modified: string | undefined;
}
export type SendingSubdomain = Resource<
SendingSubdomainTypeId,
SendingSubdomainProps,
SendingSubdomainAttributes,
never,
Providers
>;
/**
* 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).
*
* Changing `name` or `zoneId` triggers a replacement; `previewEnabled` is
* updated in place.
*
* 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.
* ### Registering a sending subdomain
* **Example:** Send mail from `mail.example.com`
* ```typescript
* 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
* ```
*
* ### Message previews
* **Example:** Keep no copies of sent messages in the activity log
* ```typescript
* const sending = yield* Cloudflare.Email.SendingSubdomain("Mail", {
* zoneId: zone.zoneId,
* name: "mail.example.com",
* previewEnabled: false,
* });
* ```
*
* ### Externally-hosted zones
* **Example:** Look up the DNS records to create manually
* ```typescript
* 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);
* ```
*
* @see https://developers.cloudflare.com/email-sending/
*
* @resource
* @product Email
* @category Email
*/
export const SendingSubdomain = Resource<SendingSubdomain>(SendingSubdomainTypeId, {
aliases: ["Cloudflare.EmailSendingSubdomain"],
});
/**
* Returns true if the given value is an SendingSubdomain resource.
*/
export const isSendingSubdomain = (value: unknown): value is SendingSubdomain =>
Predicate.hasProperty(value, "Type") && value.Type === SendingSubdomainTypeId;
export const SendingSubdomainProvider = () =>
Provider.succeed(SendingSubdomain, {
// Only `previewEnabled` changes in place.
stables: ["subdomainId", "zoneId", "name", "dkimSelector", "returnPathDomain", "created"],
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// Sending subdomains are zone-scoped (`/zones/{id}/email/sending/
// subdomains`) with no account-wide list — enumerate every zone and
// list its subdomains, then flatten.
const zones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
zones,
(zone) =>
emailSending.listSubdomains.pages({ zoneId: zone.id }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).map((subdomain) => toAttributes(subdomain, zone.id)),
),
),
// Email Sending may be unavailable / plan-gated on a zone —
// skip those zones rather than fail the whole enumeration.
Effect.catchTag("Forbidden", () => Effect.succeed([])),
),
{ concurrency: 10 },
);
return rows.flat();
}),
diff: Effect.fn(function* ({ olds = {}, news }) {
const o = olds as SendingSubdomainProps;
const n = news as SendingSubdomainProps;
// `name` and `zoneId` are identity; `previewEnabled` updates in place.
if (o.name !== undefined && o.name !== n.name) {
return { action: "replace" } as const;
}
// zoneId is Input<string>; compare only once both are concrete.
if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ output, olds }) {
const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
if (!zoneId) return undefined;
// Owned path: refresh by our persisted subdomain id.
if (output?.subdomainId) {
const observed = yield* getSubdomain(zoneId, output.subdomainId);
if (observed) return toAttributes(observed, zoneId);
}
// Adoption path: a subdomain with this name may already exist on the
// zone. Sending subdomains carry no ownership markers, so we cannot
// prove we created it — brand it `Unowned` so the engine refuses to
// take over unless `adopt` is set.
const name = output?.name ?? olds?.name;
if (name) {
const observed = yield* findByName(zoneId, name);
if (observed) return Unowned(toAttributes(observed, zoneId));
}
return undefined;
}),
reconcile: Effect.fn(function* ({ news, output }) {
// Inputs have been resolved to concrete strings by Plan.
const zoneId = news.zoneId as string;
// 1. Observe — the subdomain id cached on `output` is a hint, not a
// guarantee: a missing subdomain falls through to the name scan
// and then to create.
let observed = output?.subdomainId
? yield* getSubdomain(zoneId, output.subdomainId)
: undefined;
// 2. Fall back to scanning the zone for a name match. Ownership has
// already been verified upstream — `read` reports existing
// subdomains as `Unowned` and the engine gates takeover behind
// the adopt policy before reconcile ever runs.
if (!observed) {
observed = yield* findByName(zoneId, news.name);
}
// 3. Ensure — create when missing. A concurrent create surfaces as
// `SendingSubdomainAlreadyExists` (Cloudflare code 2040):
// converge by re-scanning for the subdomain that won the race.
if (!observed) {
observed = yield* emailSending
.createSubdomain({ zoneId, name: news.name })
.pipe(
Effect.catchTag("SendingSubdomainAlreadyExists", (error) =>
findByName(zoneId, news.name).pipe(
Effect.flatMap((existing) =>
existing ? Effect.succeed(existing) : Effect.fail(error),
),
),
),
);
}
// 4. Sync — converge `previewEnabled` when it is declared, then wait
// for DNS validation. Cloudflare auto-creates the records on CF-hosted
// zones but validation is eventually consistent: poll briefly
// for `enabled` to flip, and return the observed state either
// way (an externally-hosted zone stays disabled until the user
// adds the records — that is not a deploy failure).
const ensured =
news.previewEnabled !== undefined && observed.previewEnabled !== news.previewEnabled
? yield* emailSending.editSubdomain({
zoneId,
subdomainId: observed.tag,
previewEnabled: news.previewEnabled,
})
: observed;
const final = ensured.enabled
? ensured
: yield* getSubdomain(zoneId, ensured.tag).pipe(
Effect.map((latest) => latest ?? ensured),
Effect.repeat({
schedule: Schedule.spaced("5 seconds"),
until: (latest) => latest.enabled,
times: 12,
}),
);
// 5. Return.
return toAttributes(final, zoneId);
}),
delete: Effect.fn(function* ({ output }) {
// Idempotent — an already-gone subdomain answers with Cloudflare
// code 2033 (`SendingSubdomainNotFound`), which is success here.
yield* emailSending
.deleteSubdomain({
zoneId: output.zoneId,
subdomainId: output.subdomainId,
})
.pipe(Effect.catchTag("SendingSubdomainNotFound", () => Effect.void));
}),
});
// ---------------------------------------------------------------------------
// API helpers
// ---------------------------------------------------------------------------
type ObservedSubdomain = emailSending.GetSubdomainResponse;
/**
* Read a sending subdomain by id, mapping "gone" (`SendingSubdomainNotFound`,
* Cloudflare error code 2033) to `undefined`.
*/
const getSubdomain = (zoneId: string, subdomainId: string) =>
emailSending.getSubdomain({ zoneId, subdomainId }).pipe(
Effect.map((subdomain): ObservedSubdomain | undefined => subdomain),
Effect.catchTag("SendingSubdomainNotFound", () => Effect.undefined),
);
/**
* Find a sending subdomain by exact name within the zone. The name is the
* subdomain's identity — Cloudflare rejects duplicates with code 2040 — so
* at most one can match.
*/
const findByName = (zoneId: string, name: string) =>
emailSending.listSubdomains.items({ zoneId }).pipe(
Stream.filter((subdomain) => subdomain.name === name),
Stream.runHead,
Effect.map(Option.getOrUndefined),
);
const toAttributes = (
subdomain: ObservedSubdomain,
zoneId: string,
): SendingSubdomainAttributes => ({
subdomainId: subdomain.tag,
zoneId,
name: subdomain.name,
enabled: subdomain.enabled,
dkimSelector: subdomain.dkimSelector ?? undefined,
returnPathDomain: subdomain.returnPathDomain ?? undefined,
previewEnabled: subdomain.previewEnabled ?? undefined,
created: subdomain.created ?? undefined,
modified: subdomain.modified ?? undefined,
});