feat(agents): add sendEmail() and rewrite email-agent example for Email Service

[whoiskatrin]

Summary

Adds sendEmail() to the Agent class for outbound email via Cloudflare Email Service, and rewrites examples/email-agent into a full-stack app that demonstrates both outbound sends and inbound routing.

What changed

SDK: sendEmail() method (packages/agents)

New method on the Agent class for sending email through a send_email binding:

await this.sendEmail({
  binding: this.env.EMAIL,
  to: "user@example.com",
  from: { email: "support@example.com", name: "Bot" },
  subject: "Hello",
  text: "Welcome!",
  secret: this.env.EMAIL_SECRET  // optional HMAC signing
});

• The binding is passed explicitly at the call site — no magic property lookup.
• Automatically injects X-Agent-Name and X-Agent-ID headers on every send.
• When secret is provided, signs headers with HMAC-SHA256 so replies route back via createSecureReplyEmailResolver.
• inReplyTo option sets the In-Reply-To header for threading deferred replies.
• Emits an email:send observability event on success.
• replyToEmail() is unchanged — still uses the runtime email.reply() path for live inbound replies.

Exported types: EmailSendBinding, SendEmailOptions.

Example: email-agent full-stack rewrite

Replaces the worker-only example with a Vite + React app using Kumo:

• src/server.ts — EmailServiceAgent with @callable() methods: sendTransactionalEmail (uses this.sendEmail()), toggleAutoReply, clearActivity. Inbound via routeAgentEmail() with combined secure/address resolver. /api/simulate-email endpoint for local testing.
• src/client.tsx — compose form, inbound simulator, inbox/outbox viewer, auto-reply toggle, connection indicator, dark mode.
• Removes old src/index.ts, run-tests.ts, test-mail.ts.

Docs

• docs/email.md — rewritten for Email Service terminology. New sections: sendEmail() usage, deferred replies pattern, API reference entry. Updated secure reply routing and error handling to reference sendEmail().
• docs/agent-class.md — updated email handling example to show sendEmail().
• docs/getting-started.md, docs/index.md, README.md — "Email Routing" → "Email Service".

Validation

• npm run check passes (all 73 projects typecheck, formatting clean, linting clean, exports valid).
• npm run test:workers passes (944 tests, including 7 new sendEmail tests covering: missing binding, structured fields, In-Reply-To, HMAC signing, header merging, observability events).

Reviewer notes

• The email example depends on EMAIL_FROM being a verified sender in Cloudflare Email Service.
• EMAIL_SECRET is optional — without it the example still works but replies use address-based routing.
• The /api/simulate-email endpoint is a dev-only helper for exercising inbound routing locally.

[changeset-bot]

🦋 Changeset detected

Latest commit: fc5d3c3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1279

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1279

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1279

hono-agents

npm i https://pkg.pr.new/hono-agents@1279

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1279

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1279

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1279

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1279

commit: beef4da

[devin-ai-integration]

Devin Review found 1 potential issue.

View 5 additional findings in Devin Review.

[devin-ai-integration]

🟡 Example uses favicon.svg instead of required favicon.ico per AGENTS.md

The examples/AGENTS.md required structure mandates public/favicon.ico and the index.html template specifies <link rel="icon" href="/favicon.ico" />. This example has public/favicon.svg and <link rel="icon" href="/favicon.svg" />, which violates the mandatory convention. Most other examples (playground, mcp-client, assistant, etc.) use favicon.ico as required.

Suggested change

	<link rel="icon" href="/favicon.svg" />
	<link rel="icon" href="/favicon.ico" />

---

Was this helpful? React with 👍 or 👎 to provide feedback.