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.

[connyay]

🐛 👉 cloudflare/workers-sdk#13577

[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.