feat(worker): add send_email binding support (cloudflare#975)

* feat(worker): add send_email binding support

Adds a `SendEmail` binding and `EmailMessage` type so workers can dispatch
email via the Cloudflare Email Sending service configured under
`[[send_email]]` in wrangler.toml. Includes worker-sys bindings for
`cloudflare:email`, a runnable example under `examples/send-email`, and
integration tests.

* feat(worker): add structured Email builder for send_email binding

Extend the SendEmail binding to cover the public-beta builder overload in
addition to the raw MIME path. Adds `Email`/`EmailBuilder`, `EmailAddress`,
`EmailAttachment` (with `AttachmentContent::{Base64, Binary}`), and
`EmailSendResult { message_id }`. `SendEmail::send` now takes `&Email`;
the raw MIME path moves to `SendEmail::send_mime(&EmailMessage)`.

* address pr comments

* remove miniflare workaround

cloudflare/workers-sdk#13577 landed

* cleanup comments & example readme

* use ts-gen for email

* Auto-gen email bindings via ts-gen anonymous interface synthesis

Drops the hand-written Email/EmailBuilder/EmailAddress/EmailAttachment
types in worker/src/send_email.rs in favour of the auto-generated
SendEmailBuilder, EmailAddress, EmailAttachment, etc. that ts-gen now
synthesises from the d.ts. send_email.rs is reduced to the EnvBinding
trait impl on the auto-gen SendEmail extern type and re-exports.

types/email.d.ts renames the global EmailMessage interface to
StructuredEmailMessage to keep it unambiguously distinct from the
cloudflare:email-imported EmailMessage constructor class. The chompfile
prepends a `use email::EmailMessage` to the generated file so the
top-level send(message) signature resolves cross-module — removable
once ts-gen handles same-file module imports natively.

All 133 npm tests pass; both legacy raw-MIME and modern structured
send paths work end-to-end.

* add new_with_readable_stream test

* Pull cross-module qualification + new builder ergonomics from ts-gen

ts-gen learned three things since the last sync that simplify the
email surface here:

* Cross-module type references emit qualified Rust paths
  (`&email::EmailMessage` from a `Global` extern block referencing the
  `cloudflare:email` class). Drops the `chompfile.toml` postprocess
  that was prepending `use email::EmailMessage;` to the generated
  file.

* Built-in `web_sys` defaults — `Headers`, `Event`, `ReadableStream`,
  etc. resolve to `::web_sys::*` automatically, so those `--external`
  flags are redundant. Only the project-specific `Env` and
  `ExecutionContext` mappings remain in the chompfile.

* New dictionary builder shape: required fields go through the
  constructor, `build()` is infallible, literal discriminators
  collapse into the function name. Call sites update from
  `SendEmailBuilder::builder().from(x).build()?` to
  `SendEmailBuilder::builder(from, to, subject).build()` (or
  `::new(from, to, subject)` when no optionals are needed).

`types/email.d.ts` collapses to a single `class EmailMessage` inside
`declare module "cloudflare:email"`. The previous global-interface +
module-class split (mirroring upstream `@cloudflare/workers-types`)
was producing two distinct Rust types that both lowered to the same JS
object, which forced an `unchecked_ref` at the `reply()` call site.
Collapsed to one type they're indistinguishable in Rust.

`worker/src/send_email.rs` keeps the [`EnvBinding`] impl on top of
the auto-gen `SendEmail` extern type, plus a `#[cfg(test)]` compile
check that `SendEmail: Send` (which it is already, via the upstream
`JsValue: Send + Sync` change — no `unsafe impl Send` needed).

* Use FixedLengthStream Deref instead of unchecked_into in mime-stream test

`FixedLengthStream` already has `extends = web_sys::TransformStream` in
`worker-sys`, so wasm-bindgen auto-generates `Deref<Target = TransformStream>`
and `fixed.readable()` resolves through it. The previous
`fixed.unchecked_into::<web_sys::TransformStream>().readable()` was
unnecessarily defensive — drop the cast plus the now-unused `JsCast`
and `web_sys` imports.

* Fmt + advance ts-gen submodule to PR branch HEAD

CI's rustfmt --check flagged the dispatch_structured signature.
Apply fmt and bump the ts-gen submodule pointer to the latest
PR cloudflare#8 commit (CONVENTIONS.md rationale + emit cleanup).

* Pull doc-comment generation from ts-gen PR cloudflare#9

Each `new*` and `builder*` variant now ships with a doc block listing
its inlined literal discriminants under `# Inlined fields` and the
caller-supplied parameters under `# Parameters`, sourced from the
original getter JSDoc.

* Advance ts-gen submodule to merged main

ts-gen PR cloudflare#9 (doc comments on dictionary builder variants) merged.
Bump the submodule pointer to the merge commit on main; the
generated `worker/src/email.rs` is unchanged from the PR-branch
output.

* Advance ts-gen submodule to merged main

ts-gen PR cloudflare#10 (h2 headings + dash-separated bullets in builder docs)
merged. Bump the submodule pointer and regenerate
`worker/src/email.rs` with the updated doc format.

---------

Co-authored-by: Guy Bedford <gbedford@cloudflare.com>

Author: connyay

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "wasm-streams"]
 	path = wasm-streams
 	url = git@github.com:guybedford/wasm-streams.git
+[submodule "ts-gen"]
+	path = ts-gen
+	url = git@github.com:wasm-bindgen/ts-gen

Cargo.lock

@@ -1,5 +1,21 @@
 version = 0.1
 
+[[task]]
+name = 'build:types'
+deps = ['install:ts-gen']
+# `Env` / `ExecutionContext` are project-specific re-exports that ts-gen
+# can't infer; everything else (`ReadableStream`, `Headers`, `Event`, …)
+# resolves through ts-gen's built-in web_sys defaults.
+run = '''ts-gen --input types/email.d.ts --output worker/src/email.rs \
+  --external "Env=crate::Env" \
+  --external "ExecutionContext=crate::Context"'''
+
+[[task]]
+name = 'install:ts-gen'
+# ts-gen pulls in oxc which needs a newer rustc than the workspace's pinned 1.88;
+# build with the user's stable toolchain instead so it ignores rust-toolchain.toml.
+run = 'cargo +stable install --path ts-gen'
+
 [[task]]
 name = 'build:wasm-bindgen'
 cwd = 'wasm-bindgen'

chompfile.toml

@@ -0,0 +1,18 @@
+[package]
+name = "send-email-on-workers"
+version = "0.1.0"
+edition = "2021"
+
+[package.metadata.release]
+release = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+# Default feature `gethostname` pulls in a crate that doesn't build for
+# `wasm32-unknown-unknown`, so disable it. The remaining core API is enough
+# to assemble a message as long as we set `date` and `message_id` ourselves
+# (the auto-generated ones rely on `SystemTime::now()` / `gethostname`).
+mail-builder = { version = "0.4", default-features = false }
+worker.workspace = true

examples/send-email/Cargo.toml

@@ -0,0 +1,28 @@
+# Sending email from Cloudflare Workers
+
+Example of using `worker::SendEmail` to send a message through a `[[send_email]]` binding.
+
+Two routes:
+
+* `GET /` — the structured path. Set fields like `from`, `to`, `subject`, and `text`/`html` on [`Message::builder`](https://docs.rs/worker/latest/worker/struct.MessageBuilder.html), and the runtime assembles the MIME body for you.
+* `GET /raw` — the raw MIME path. Build the body yourself with [`mail-builder`](https://crates.io/crates/mail-builder) and hand it to [`EmailMessage`](https://docs.rs/worker/latest/worker/struct.EmailMessage.html) as-is. Reach for this when you need control over the MIME — custom headers, DKIM passthrough, VERP bounces, that sort of thing.
+
+## Local development
+
+`wrangler dev --local` won't actually send anything. As the [Cloudflare docs](https://developers.cloudflare.com/email-routing/email-workers/local-development/) explain, outbound messages get written to a local `.eml` file. Wrangler prints the path so you can open it and check the raw message.
+
+```bash
+npm install
+npm run dev
+# then, in another shell:
+curl http://localhost:8787/        # structured
+curl http://localhost:8787/raw     # raw MIME
+```
+
+## Deploying
+
+Verify the sender and recipient addresses first (see the [Cloudflare email API docs](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/)), then:
+
+```bash
+npm run deploy
+```

examples/send-email/README.md

@@ -0,0 +1,12 @@
+{
+	"name": "send-email-on-workers",
+	"version": "0.0.0",
+	"private": true,
+	"scripts": {
+		"deploy": "cargo install worker-build ; wrangler deploy",
+		"dev": "cargo install worker-build ; wrangler dev --local"
+	},
+	"devDependencies": {
+		"wrangler": "^4.83.0"
+	}
+}

examples/send-email/package.json

@@ -0,0 +1,55 @@
+use mail_builder::MessageBuilder as MimeBuilder;
+use worker::*;
+
+const SENDER: &str = "sender@example.com";
+const RECIPIENT: &str = "recipient@example.com";
+
+#[event(fetch)]
+async fn fetch(req: Request, env: Env, _ctx: Context) -> Result<Response> {
+    let sender = env.send_email("EMAIL")?;
+
+    let result = match req.path().as_str() {
+        "/" => send_structured(&sender).await?,
+        "/raw" => send_raw_mime(&sender).await?,
+        // Don't dispatch on favicon / unknown paths — otherwise every browser
+        // tab to localhost sends a real email in `wrangler dev`.
+        _ => return Response::error("not found", 404),
+    };
+
+    Response::ok(format!("sent: {}", result.message_id()))
+}
+
+async fn send_structured(sender: &SendEmail) -> Result<EmailSendResult> {
+    let from = EmailAddress::new("Sending email test", SENDER);
+    let builder = SendEmailBuilder::builder_with_email_address_and_str(
+        &from,
+        RECIPIENT,
+        "An email generated in a Worker",
+    )
+    .text("Congratulations, you just sent an email from a Worker.")
+    .html("<p>Congratulations, you just sent an email from a Worker.</p>")
+    .build();
+
+    Ok(sender.send_with_builder(&builder).await?)
+}
+
+async fn send_raw_mime(sender: &SendEmail) -> Result<EmailSendResult> {
+    // mail-builder's auto-generated `Date:` and `Message-ID:` headers rely on
+    // `SystemTime::now()` and `gethostname`, neither of which work on
+    // `wasm32-unknown-unknown`. https://github.com/stalwartlabs/mail-builder/pull/26
+    let now_ms = Date::now().as_millis();
+    let message_id = format!("{now_ms}@example.com");
+
+    let raw = MimeBuilder::new()
+        .from(("Sending email test", SENDER))
+        .to(RECIPIENT)
+        .subject("An email generated in a Worker")
+        .date((now_ms / 1000) as i64)
+        .message_id(message_id)
+        .text_body("Congratulations, you just sent an email from a Worker.")
+        .write_to_string()
+        .map_err(|e| Error::RustError(e.to_string()))?;
+
+    let message = EmailMessage::new(SENDER, RECIPIENT, &raw)?;
+    Ok(sender.send(&message).await?)
+}

examples/send-email/src/lib.rs

@@ -0,0 +1,11 @@
+name = "send-email-on-workers"
+main = "build/index.js"
+compatibility_date = "2024-10-01"
+
+[build]
+command = "cargo install \"worker-build@^0.8\" && worker-build --release"
+# For development: use local worker-build binary
+# command = "../../target/release/worker-build --release"
+
+[[send_email]]
+name = "EMAIL"

examples/send-email/wrangler.toml

@@ -15,7 +15,7 @@
   "homepage": "https://github.com/cloudflare/workers-rs#readme",
   "devDependencies": {
     "@types/node": "^24.0.1",
-    "miniflare": "^4.20260421.0",
+    "miniflare": "^4.20260424.0",
     "typescript": "^5.8.3",
     "uuid": "^14.0.0",
     "vitest": "^3.2.4"