feat(cloudflare/workers): add Email event source for inbound mail

[sam-goodwin]

Adds Cloudflare.email({ zone }).subscribe(handler) — one call wires both halves of an Email Worker consumer:

• Runtime: registers the email event listener on the Worker.
• Deploy-time: the EmailEventSourcePolicy yields a sibling EmailRouting toggle on the zone and an EmailRule whose actions: [{ type: "worker", … }] targets this Worker — mirroring the QueueEventSource policy pattern.

import * as Cloudflare from "alchemy/Cloudflare";
import * as Effect from "effect/Effect";

export default Cloudflare.Worker(
  "Inbox",
  { main: import.meta.path },
  Effect.gen(function* () {
    yield* Cloudflare.email({ zone: "example.com" }).subscribe((message) =>
      message.forward("ops@example.com"),
    );
    return {};
  }).pipe(Effect.provide(Cloudflare.EmailEventSourceLive)),
);

alchemy.run.ts no longer needs hand-rolled EmailRouting + EmailRule calls.

Filtering and dispatching in the handler

matchers scopes which envelopes Cloudflare delivers to this Worker (the auto-created EmailRule); inside the handler you branch on the message and use the Effect-wrapped actions. A real-world inbox might look like this:

Effect.gen(function* () {
  const tickets = yield* Cloudflare.R2Bucket.bind(Tickets);
  const ops = yield* Cloudflare.EmailAddress.bind(OpsEmail);

  yield* Cloudflare.email({
    zone: "example.com",
    // Only route mail addressed to the inboxes we care about.
    matchers: [
      { type: "literal", field: "to", value: "support@example.com" },
      { type: "literal", field: "to", value: "billing@example.com" },
    ],
    priority: 10,
  }).subscribe((message) => {
    // Reject anything Cloudflare's spam pipeline flagged.
    if (message.headers.get("x-spam-score") === "high") {
      return message.setReject("Rejected: spam");
    }

    // support@ — archive the raw RFC 5322 bytes in R2 and ack.
    if (message.to === "support@example.com") {
      return tickets.put(`/inbox/${crypto.randomUUID()}`, message.body, {
        httpMetadata: { contentType: "message/rfc822" },
      });
    }

    // billing@ — forward, fall back to a bounce if the destination
    // is unverified or Cloudflare otherwise rejects the forward.
    return message.forward(ops.email).pipe(
      Effect.catchTag("EmailError", () =>
        message.setReject("Billing inbox unavailable"),
      ),
    );
  });
}).pipe(
  Effect.provide(Cloudflare.EmailEventSourceLive),
  Effect.provide(Cloudflare.R2BucketBindingLive),
);

The catch-all ({ type: "all" }) is the default if you omit matchers. To run with no EmailRule at all (manage routing yourself), call email() with no zone — the policy becomes a no-op.

Message wrapper

Matches the R2 / KV binding convention — message.raw is the underlying cf.ForwardableEmailMessage (escape hatch); ergonomic fields and Effect-wrapped actions sit on top:

interface ForwardableEmailMessage {
  readonly raw: cf.ForwardableEmailMessage;
  readonly from: string;
  readonly to: string;
  readonly headers: cf.Headers;
  readonly body: cf.ReadableStream<Uint8Array>;
  readonly bodySize: number;
  setReject(reason: string): Effect.Effect<void>;
  forward(rcptTo: string, headers?: cf.Headers): Effect.Effect<void, EmailError>;
  reply(message: cf.EmailMessage): Effect.Effect<void, EmailError>;
}

The cf names raw / rawSize (the message body and its size) are exposed as body / bodySize to avoid clashing with the raw escape hatch.

Notes

• email is already in ExportedHandlerMethods on Worker.ts, so the runtime dispatch table wires this up automatically.
• EmailEventSourcePolicy registered in Cloudflare.providers() alongside QueueEventSourcePolicy / CronEventSourcePolicy.
• One subscribe per Worker (the runtime fans every email event out to every registered listener, so per-rule dispatch is handled inside the single handler via message.to / headers — exactly like the example above).
• Tutorial added at website/src/content/docs/tutorial/cloudflare/email-worker.mdx.
• JSDoc annotated with @binding / @section / @example so bun generate:api-reference emits providers/Cloudflare/EmailEventSource.md.

[alchemy-version-bot]

Install the packages built from this commit:

alchemy

bun add alchemy@https://pkg.ing/alchemy/c3ac23a

@alchemy.run/better-auth

bun add @alchemy.run/better-auth@https://pkg.ing/@alchemy.run/better-auth/c3ac23a

@alchemy.run/pr-package

bun add @alchemy.run/pr-package@https://pkg.ing/@alchemy.run/pr-package/c3ac23a

[sam-goodwin]

@Mkassabov i don't have an account with email testing capability. Can you set up our test account and drive this home?