feat(worker): add send_email binding support

[connyay]

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.

[connyay]

There are currently two open PRs around workers + email: #624 #715

Sorry for further muddying the waters here. I opened this with the narrow focus on sending + tests + example. If this lands I am happy to work on email recieving in a follow up.

[edevil]

Duplicate headers silently collapse — worker/src/send_email.rs:335-341, 353-362

The field comment on Email::headers says Vec<(String, String)> is used because "duplicate header names are meaningful in RFC 5322," but the serialization path makes duplicates unreachable:

• serialize_headers calls SerializeMap::serialize_entry for each pair.
• The encoder (line 103) is Serializer::new().serialize_maps_as_objects(true), so the map becomes a plain JS object — duplicate keys overwrite.
• The runtime-side type is jsg::Dict<kj::String> (also a map; no duplicates).

So duplicates silently collapse to the last value instead of being preserved. Two ways to tighten:

1. Drop the RFC 5322 claim and back the field with a BTreeMap<String, String> (or HashMap) so the type reflects what actually gets sent.
2. Error on duplicates in EmailBuilder::build() so callers don't lose data without noticing.

(1) is simpler and fine given the runtime can't represent duplicates anyway.

[edevil]

AttachmentContent::Base64 is misnamed — the runtime does not base64-decode string content — worker/src/send_email.rs:221-250

The runtime treats attachment string content as UTF-8 bytes, not base64. The function in edgeworker that feeds the mail stream does this:

kj::ArrayPtr<kj::byte> getArrayPtrFromContent(kj::OneOf<kj::String, jsg::BufferSource>& content) {
  KJ_SWITCH_ONEOF(content) {
    KJ_CASE_ONEOF(string, kj::String)        { return string.asBytes(); }
    KJ_CASE_ONEOF(buffer, jsg::BufferSource) { return buffer.asArrayPtr(); }
  }
}

kj::String::asBytes() returns raw UTF-8 — no base64 decoding happens. So:

• AttachmentContent::Base64("Hello, World!") → recipient gets the text Hello, World!. Works, despite the name.
• AttachmentContent::Base64("JVBERi0xLjQK…") (a user who followed the public docs and pre-base64-encoded a PDF) → recipient gets the literal ASCII of the base64 string, not the decoded PDF. Broken, silently.

(Sidebar: the public docs at email-service/api/send-emails/workers-api/ claim content: string | ArrayBuffer; // Base64 string or binary content — that contradicts the runtime and should be filed as a docs bug.)

Suggested fix — rename to reflect actual semantics

pub enum AttachmentContent {
    Text(String),      // sent as UTF-8 bytes on the wire
    Bytes(Vec<u8>),    // sent as Uint8Array
}

with the obvious From impls (&str/String → Text, &[u8]/Vec<u8> → Bytes) and a doc note: "If your source is base64, decode it to bytes first." This matches the runtime's OneOf<String, BufferSource> faithfully and removes the footgun.

[guybedford]

@connyay I'd be interested to get your feedback here - I was able to update this API to use a new automated bindgen from ts-gen as an additional commit, which basically just automates the src/email.rs file entirely. This would be a nice self-contained subsystem to test the output on. Please take a look and let me know what you think of the differences.

[codspeed-hq]

Merging this PR will not alter performance

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

✅ 2 untouched benchmarks

---

_{Comparing connyay:cjh-sending-email (4b72d0b) with main (fd18681)}

[connyay]

@guybedford that looks great! ts-gen should be a slam dunk for flagship #979 👀 - I can rework that after this lands or you are welcome to use that as a testbed as it should be a pretty straight forward generation.

few notes on email:

1. ForwardableEmailMessage::reply() is awkward to call from Rust. The generated signature is reply(this, message: &StructuredEmailMessage) (email.rs:181), but StructuredEmailMessage only has readonly from/to getters — no setters, no builder, no way to populate fields from Rust. At runtime you want to pass an EmailMessage class instance from cloudflare:email, which is now a distinct Rust type with no extends = StructuredEmailMessage, so the call site ends up doing email_msg.unchecked_ref::<StructuredEmailMessage>(). That's the same unchecked_ref shape the d.ts EDIT note was trying to eliminate — reply() is the one place it still shows up. There aren't any tests on reply() yet, which is probably why this hasn't come up.

A couple of options: have ts-gen emit extends = StructuredEmailMessage on the class form, or retype reply's parameter as the class — that second one may also better match the runtime contract, since reply() likely expects a cloudflare:email EmailMessage instance (with body) rather than a bare envelope object, which would mean the d.ts itself is mistyped here.

2.unsafe impl Send for SendEmail {} is missing.
3. maybe this is my go tendencies showing but SendEmailBuilder::builder().from(...).build()? is awkward.

[guybedford]

@connyay I've fixed up the EmailMessage interface now, with some work on ts-gen to make it compile. Please take a look and let me know if this seems correct now.

unsafe impl Send is no longer necessary since JsValue became send in wasm bindgen. I added a test to verify.

For (3), builders are important for providing optimized bindgen (this is a future optimization we want to add, not just relying on serde for our own sledgehammer style bindings).

I've added a few fixes for the ergonomics here, please take another look:

1. builder() now takes required arguments instead of having setters for them
2. As a result, builder() expands to the union and overload variants like all functions
3. String literal args are now treated as overload variations so we get builder_inline(..) and builder_attachment(...) as separate builder constructors.
4. I then added a new(required) function that mirrors the builder(required).build() as a short-hand. While not as useful for the email builder, it is a low cost wrapper with little bloat and enables EmailAddress::new("name", "addr") and EmailAttachment::new_inline(content, filename, type_) to now work directly.

[connyay]

This is delightful - ship it!