fix(types): ForwardableEmailMessage omits the documented canBeForwarded property

Empieza con types/defines/email.d.ts y examina la declaración de ForwardableEmailMessage. Compárala con la interfaz documentada en src/content/docs/email-service/api/route-emails/email-handler.mdx y, después, comprueba que el tipo de la propiedad coincida con el booleano de solo lectura documentado. El trabajo estará terminado cuando la declaración incluya la propiedad documentada y la reproducción de TypeScript proporcionada pase la comprobación de tipos.

Summary

The Email Service documentation page "Workers API" lists readonly canBeForwarded: boolean on ForwardableEmailMessage, the message passed to an email() handler, and the production email API source that #8222 moves into workerd exposes that property. The generated types do not declare it: neither the published @cloudflare/workers-types nor the runtime types that wrangler types generates contain canBeForwarded. A TypeScript Worker that reads message.canBeForwarded, as the documentation describes, fails type checking with TS2339.

Runtime or environment

• @cloudflare/workers-types 5.20261108.1 (the latest npm dist-tag when tested)
• wrangler 4.158.0 (latest on npm), whose generated worker-configuration.d.ts header reads "Runtime types generated with [email protected]"
• TypeScript 7.0.2
• workerd main at ea82ea73e8813a8fef9df28afb8ba6fa55fd4710, file types/defines/email.d.ts
• cloudflare-docs production at 2a4bfc47c14e4943329abbb2f741b897c7184071
• PR #8222 head b3267af57e368a5c22e5a5af86fd42bb66d5fdd4
• Node.js 26.12.1, npm 12.2.1, macOS 27.2 (arm64)

Steps to reproduce

1. In an empty directory, run npm install @cloudflare/[email protected] [email protected].
2. Create tsconfig.json:

{ "compilerOptions": { "target": "es2024", "module": "es2022", "moduleResolution": "bundler", "lib": ["es2024"], "types": ["@cloudflare/workers-types"], "strict": true, "noEmit": true }, "include": ["src"] }

3. Create src/index.ts:

export default {
  async email(message: ForwardableEmailMessage, env: unknown, ctx: ExecutionContext): Promise<void> {
    if (message.canBeForwarded) {
      await message.forward("[email protected]");
    } else {
      message.setReject("Message cannot be forwarded");
    }
  },
} satisfies ExportedHandler;

4. Run npx tsc -p ..
5. Optional second route: add a wrangler.jsonc with { "name": "email-types-check", "main": "src/index.ts", "compatibility_date": "2026-11-08" }, run npx [email protected] types, set "types": [] and add worker-configuration.d.ts to include in tsconfig.json, then run npx tsc -p . again.

Expected behavior

The documentation page "Workers API" (src/content/docs/email-service/api/route-emails/email-handler.mdx, section "ForwardableEmailMessage interface") defines the incoming message as including readonly canBeForwarded: boolean; // Whether the message can be forwarded. The type for the email() handler's message should declare that read-only boolean, so the reproduction file type-checks and message.canBeForwarded has type boolean.

Actual behavior

Both type sources reject the property. With the published package, npx tsc -p . exits with status 1:

src/index.ts(3,17): error TS2339: Property 'canBeForwarded' does not exist on type 'ForwardableEmailMessage'.

The wrangler types route produces the same TS2339 error at the same location. grep -c canBeForwarded returns 0 for index.d.ts, index.ts, experimental/index.d.ts, and experimental/index.ts in the package, and for the generated worker-configuration.d.ts. The ForwardableEmailMessage interface in types/defines/email.d.ts on main declares raw, headers, rawSize, setReject, forward, and two reply overloads, but no canBeForwarded. As a control, replacing message.canBeForwarded with message.rawSize > 0 in the same file compiles with exit status 0.

Evidence

• Expected source: cloudflare-docs src/content/docs/email-service/api/route-emails/email-handler.mdx line 64, readonly canBeForwarded: boolean; // Whether the message can be forwarded, also shown on the live page https://developers.cloudflare.com/email-service/api/route-emails/email-handler/; corroborated by #8222 src/workerd/api/email.h at the PR head, which registers JSG_READONLY_PROTOTYPE_PROPERTY(canBeForwarded, getCanBeForwarded); in ForwardableEmailMessage's JSG_RESOURCE_TYPE (line 278) and documents the backing IncomingEmail field as "Only authenticated messages may be forwarded." (line 174)
• Failure source: TS2339 from tsc against @cloudflare/workers-types and against wrangler types output, plus the ForwardableEmailMessage declaration in types/defines/email.d.ts at the main commit above.
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

The production runtime was not tested: the test account has no Email Routing zone, so no email() handler received a real message. That the property exists in production rests on the documentation and on #8222's description that it moves the internal email code into workerd "as-is". The local wrangler dev runtime is a separate implementation and is not part of this report.

Restoration check

Rerun the reproduction with the fixing @cloudflare/workers-types release in place of 5.20261108.1, and with wrangler types from a wrangler release that bundles the fixed workerd: src/index.ts type-checks with exit status 0 on both routes. To confirm the declared type is a required read-only boolean rather than optional or any, const b: boolean = message.canBeForwarded; compiles under strict, const s: string = message.canBeForwarded; fails with TS2322, and message.canBeForwarded = false; fails with TS2540. The control file still compiles, and existing ForwardableEmailMessage members keep their current types.

References

• #8222 (open PR, "Move email.h/c++ APIs to workerd")
• #2283 and #2414: earlier report and fix for a different missing ForwardableEmailMessage member (reply)

Triage assessment

• Impact level: P2
• Assessment status: provisional
• Impact basis: Type checking fails (tsc exits 1 with TS2339) for any Worker that reads the documented message.canBeForwarded, on both the published package and wrangler types output; the failure is bounded to code that reads this one property, and wrangler deploy bundling, which does not type-check, is not blocked. The level is provisional because the property's presence in production was not observed directly; if production lacks it, the defect is in the documentation instead.
• Workaround status: available
• Workaround basis: Declaring interface ForwardableEmailMessage { readonly canBeForwarded: boolean; } in a project .d.ts file merges with the published global interface; with that file added, the reproduction compiled with exit status 0 under the same package and compiler. The declaration only asserts the documented production shape: the local wrangler dev email simulation in wrangler 4.158.0 does not set the property, so it reads as undefined there.