---
title: Email agent
description: Build an agent that sends, receives, routes, and replies to email using Cloudflare Email Service and the Agents SDK.
image: https://edgetunnel-b2h.pages.dev/dev-products-preview.png
---

> Documentation Index  
> Fetch the complete documentation index at: https://edgetunnel-b2h.pages.dev/agents/llms.txt  
> Use this file to discover all available pages before exploring further. 

[Skip to content](#%5Ftop) 

# Email agent

Agents can send and receive email with Cloudflare [Email Service](https://edgetunnel-b2h.pages.dev/email-service/api/route-emails/email-handler/). This guide shows how to send outbound email with the Workers binding, route inbound mail into Agents, and handle follow-up replies securely.

## Prerequisites

Before using email with Agents, you need:

1. A domain onboarded to [Cloudflare Email Service](https://edgetunnel-b2h.pages.dev/email-service/).
2. A `send_email` binding in `wrangler.jsonc` for outbound email.
3. An Email Service routing rule that sends inbound mail to your Worker.
4. Optional: an `EMAIL_SECRET` secret if you want secure reply routing.

### Domain setup

1. Log in to the [Cloudflare Dashboard ↗](https://dash.cloudflare.com).
2. Go to **Compute & AI** \> **Email Service**.
3. Select **Onboard Domain** and choose your domain.
4. Add the DNS records (SPF and DKIM) to authorize sending.

DNS changes usually complete within 5-15 minutes for domains using Cloudflare DNS, but can take up to 24 hours to propagate globally.

### Wrangler configuration

Add the email binding to your Worker:

* [  wrangler.jsonc ](#tab-panel-5931)
* [  wrangler.toml ](#tab-panel-5932)

**JSONC**

```jsonc
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "send_email": [
    {
      "name": "EMAIL",
      "remote": true
    }
  ]
}
```

**TOML**

```toml
[[send_email]]
name = "EMAIL"
remote = true
```

The `remote = true` option lets you call the real Email Service API during local development with `wrangler dev`.

## Quick start

* [  JavaScript ](#tab-panel-5957)
* [  TypeScript ](#tab-panel-5958)

**JavaScript**

```js
import { Agent, callable, routeAgentEmail } from "agents";
import { createAddressBasedEmailResolver } from "agents/email";
import PostalMime from "postal-mime";


export class EmailAgent extends Agent {
  @callable()
  async sendWelcomeEmail(to) {
    await this.sendEmail({
      binding: this.env.EMAIL,
      to,
      from: "support@yourdomain.com",
      replyTo: "support@yourdomain.com",
      subject: "Welcome to our service",
      text: "Thanks for signing up. Reply to this email if you need help.",
    });
  }


  async onEmail(email) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    console.log("Received email from:", email.from);
    console.log("Subject:", parsed.subject);


    await this.replyToEmail(email, {
      fromName: "Support Agent",
      body: "Thanks for your email! We received it.",
    });
  }
}


export default {
  async email(message, env) {
    await routeAgentEmail(message, env, {
      resolver: createAddressBasedEmailResolver("EmailAgent"),
    });
  },
};
```

**TypeScript**

```ts
import { Agent, callable, routeAgentEmail } from "agents";
import { createAddressBasedEmailResolver, type AgentEmail } from "agents/email";
import PostalMime from "postal-mime";


export class EmailAgent extends Agent {
  @callable()
  async sendWelcomeEmail(to: string) {
    await this.sendEmail({
      binding: this.env.EMAIL,
      to,
      from: "support@yourdomain.com",
      replyTo: "support@yourdomain.com",
      subject: "Welcome to our service",
      text: "Thanks for signing up. Reply to this email if you need help.",
    });
  }


  async onEmail(email: AgentEmail) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    console.log("Received email from:", email.from);
    console.log("Subject:", parsed.subject);


    await this.replyToEmail(email, {
      fromName: "Support Agent",
      body: "Thanks for your email! We received it.",
    });
  }
}


export default {
  async email(message, env) {
    await routeAgentEmail(message, env, {
      resolver: createAddressBasedEmailResolver("EmailAgent"),
    });
  },
} satisfies ExportedHandler<Env>;
```

## Sending outbound email

### Using `sendEmail()`

`sendEmail()` sends outbound email through a `send_email` binding that you pass explicitly. It automatically injects agent routing headers (`X-Agent-Name`, `X-Agent-ID`) into every message, and optionally signs them with HMAC-SHA256 so that replies can be routed back to the same agent instance.

* [  JavaScript ](#tab-panel-5941)
* [  TypeScript ](#tab-panel-5942)

**JavaScript**

```js
class MyAgent extends Agent {
  @callable()
  async sendReceipt(to, orderId) {
    const result = await this.sendEmail({
      binding: this.env.EMAIL,
      to,
      from: { email: "billing@yourdomain.com", name: "Billing Bot" },
      replyTo: "billing@yourdomain.com",
      subject: `Receipt for order ${orderId}`,
      text: `Your receipt for order ${orderId} is ready.`,
      secret: this.env.EMAIL_SECRET,
    });


    return result.messageId;
  }
}
```

**TypeScript**

```ts
class MyAgent extends Agent {
  @callable()
  async sendReceipt(to: string, orderId: string) {
    const result = await this.sendEmail({
      binding: this.env.EMAIL,
      to,
      from: { email: "billing@yourdomain.com", name: "Billing Bot" },
      replyTo: "billing@yourdomain.com",
      subject: `Receipt for order ${orderId}`,
      text: `Your receipt for order ${orderId} is ready.`,
      secret: this.env.EMAIL_SECRET,
    });


    return result.messageId;
  }
}
```

When `secret` is provided, the agent signs the routing headers so that replies verified by `createSecureReplyEmailResolver` route back to the same agent instance.

Set `replyTo` to the mailbox that routes back to your Worker when you want recipients to continue the conversation with the same agent.

## Routing inbound mail

Resolvers determine which Agent instance receives an incoming email. Choose the resolver that matches your use case.

For basic Email Service sending and receiving, `createAddressBasedEmailResolver()` is enough. The secure reply resolver below is optional and specific to Agents SDK reply signing, not a requirement of Email Service itself.

### `createAddressBasedEmailResolver`

Recommended for inbound mail. Routes emails based on the recipient address.

* [  JavaScript ](#tab-panel-5935)
* [  TypeScript ](#tab-panel-5936)

**JavaScript**

```js
import { createAddressBasedEmailResolver } from "agents/email";


const resolver = createAddressBasedEmailResolver("EmailAgent");
```

**TypeScript**

```ts
import { createAddressBasedEmailResolver } from "agents/email";


const resolver = createAddressBasedEmailResolver("EmailAgent");
```

**Routing logic:**

| Recipient Address                     | Agent Name           | Agent ID |
| ------------------------------------- | -------------------- | -------- |
| support@example.com                   | EmailAgent (default) | support  |
| sales@example.com                     | EmailAgent (default) | sales    |
| NotificationAgent+user123@example.com | NotificationAgent    | user123  |

The sub-address format (`agent+id@domain`) allows routing to different agent namespaces and instances from a single email domain.

Note

Agent class names in the recipient address are matched case-insensitively. Email infrastructure often lowercases addresses, so `NotificationAgent+user123@example.com` and `notificationagent+user123@example.com` both route to the `NotificationAgent` class.

### `createSecureReplyEmailResolver`

For reply flows with signature verification. Verifies that incoming emails are authentic replies to your outbound emails, preventing attackers from routing emails to arbitrary agent instances.

* [  JavaScript ](#tab-panel-5937)
* [  TypeScript ](#tab-panel-5938)

**JavaScript**

```js
import { createSecureReplyEmailResolver } from "agents/email";


const resolver = createSecureReplyEmailResolver(env.EMAIL_SECRET);
```

**TypeScript**

```ts
import { createSecureReplyEmailResolver } from "agents/email";


const resolver = createSecureReplyEmailResolver(env.EMAIL_SECRET);
```

When your agent sends an email with `replyToEmail()` or `sendEmail()` and a `secret`, it signs the routing headers with a timestamp. When a reply comes back, this resolver verifies the signature and checks that it has not expired before routing.

**Options:**

* [  JavaScript ](#tab-panel-5943)
* [  TypeScript ](#tab-panel-5944)

**JavaScript**

```js
const resolver = createSecureReplyEmailResolver(env.EMAIL_SECRET, {
  // Maximum age of signature in seconds (default: 30 days)
  maxAge: 7 * 24 * 60 * 60, // 7 days


  // Callback for logging/debugging signature failures
  onInvalidSignature: (email, reason) => {
    console.warn(`Invalid signature from ${email.from}: ${reason}`);
    // reason can be: "missing_headers", "expired", "invalid", "malformed_timestamp"
  },
});
```

**TypeScript**

```ts
const resolver = createSecureReplyEmailResolver(env.EMAIL_SECRET, {
  // Maximum age of signature in seconds (default: 30 days)
  maxAge: 7 * 24 * 60 * 60, // 7 days


  // Callback for logging/debugging signature failures
  onInvalidSignature: (email, reason) => {
    console.warn(`Invalid signature from ${email.from}: ${reason}`);
    // reason can be: "missing_headers", "expired", "invalid", "malformed_timestamp"
  },
});
```

**When to use:** If your agent initiates email conversations and you need replies to route back to the same agent instance securely.

### `createCatchAllEmailResolver`

For single-instance routing. Routes all emails to a specific agent instance regardless of the recipient address.

* [  JavaScript ](#tab-panel-5939)
* [  TypeScript ](#tab-panel-5940)

**JavaScript**

```js
import { createCatchAllEmailResolver } from "agents/email";


const resolver = createCatchAllEmailResolver("EmailAgent", "default");
```

**TypeScript**

```ts
import { createCatchAllEmailResolver } from "agents/email";


const resolver = createCatchAllEmailResolver("EmailAgent", "default");
```

**When to use:** When you have a single agent instance that handles all emails (for example, a shared inbox).

### Combining resolvers

You can combine resolvers to handle different scenarios:

* [  JavaScript ](#tab-panel-5955)
* [  TypeScript ](#tab-panel-5956)

**JavaScript**

```js
export default {
  async email(message, env) {
    const secureReplyResolver = createSecureReplyEmailResolver(
      env.EMAIL_SECRET,
    );
    const addressResolver = createAddressBasedEmailResolver("EmailAgent");


    await routeAgentEmail(message, env, {
      resolver: async (email, env) => {
        // First, check if this is a signed reply
        const replyRouting = await secureReplyResolver(email, env);
        if (replyRouting) return replyRouting;


        // Otherwise, route based on recipient address
        return addressResolver(email, env);
      },


      // Handle emails that do not match any routing rule
      onNoRoute: (email) => {
        console.warn(`No route found for email from ${email.from}`);
        email.setReject("Unknown recipient");
      },
    });
  },
};
```

**TypeScript**

```ts
export default {
  async email(message, env) {
    const secureReplyResolver = createSecureReplyEmailResolver(
      env.EMAIL_SECRET,
    );
    const addressResolver = createAddressBasedEmailResolver("EmailAgent");


    await routeAgentEmail(message, env, {
      resolver: async (email, env) => {
        // First, check if this is a signed reply
        const replyRouting = await secureReplyResolver(email, env);
        if (replyRouting) return replyRouting;


        // Otherwise, route based on recipient address
        return addressResolver(email, env);
      },


      // Handle emails that do not match any routing rule
      onNoRoute: (email) => {
        console.warn(`No route found for email from ${email.from}`);
        email.setReject("Unknown recipient");
      },
    });
  },
} satisfies ExportedHandler<Env>;
```

## Handling emails in your Agent

### The `AgentEmail` interface

When your agent's `onEmail` method is called, it receives an `AgentEmail` object:

**TypeScript**

```ts
type AgentEmail = {
  from: string; // Sender's email address
  to: string; // Recipient's email address
  headers: Headers; // Email headers (subject, message-id, etc.)
  rawSize: number; // Size of the raw email in bytes


  getRaw(): Promise<Uint8Array>; // Get the full raw email content
  reply(options): Promise<void>; // Send a reply
  forward(rcptTo, headers?): Promise<void>; // Forward the email
  setReject(reason): void; // Reject the email with a reason
};
```

### Parsing email content

Use a library like [postal-mime ↗](https://www.npmjs.com/package/postal-mime) to parse the raw email:

* [  JavaScript ](#tab-panel-5945)
* [  TypeScript ](#tab-panel-5946)

**JavaScript**

```js
import PostalMime from "postal-mime";


class MyAgent extends Agent {
  async onEmail(email) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    console.log("Subject:", parsed.subject);
    console.log("Text body:", parsed.text);
    console.log("HTML body:", parsed.html);
    console.log("Attachments:", parsed.attachments);
  }
}
```

**TypeScript**

```ts
import PostalMime from "postal-mime";


class MyAgent extends Agent {
  async onEmail(email: AgentEmail) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    console.log("Subject:", parsed.subject);
    console.log("Text body:", parsed.text);
    console.log("HTML body:", parsed.html);
    console.log("Attachments:", parsed.attachments);
  }
}
```

### Detecting auto-reply emails

Use `isAutoReplyEmail()` to detect auto-reply emails and avoid mail loops:

* [  JavaScript ](#tab-panel-5949)
* [  TypeScript ](#tab-panel-5950)

**JavaScript**

```js
import { isAutoReplyEmail } from "agents/email";
import PostalMime from "postal-mime";


class MyAgent extends Agent {
  async onEmail(email) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    // Detect auto-reply emails to avoid sending duplicate responses
    if (isAutoReplyEmail(parsed.headers)) {
      console.log("Skipping auto-reply email");
      return;
    }


    // Process the email...
  }
}
```

**TypeScript**

```ts
import { isAutoReplyEmail } from "agents/email";
import PostalMime from "postal-mime";


class MyAgent extends Agent {
  async onEmail(email: AgentEmail) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    // Detect auto-reply emails to avoid sending duplicate responses
    if (isAutoReplyEmail(parsed.headers)) {
      console.log("Skipping auto-reply email");
      return;
    }


    // Process the email...
  }
}
```

This checks for standard RFC 3834 headers (`Auto-Submitted`, `X-Auto-Response-Suppress`, `Precedence`) that indicate an email is an auto-reply.

### Replying to emails

Use `this.replyToEmail()` to send a reply through the inbound email's reply channel:

* [  JavaScript ](#tab-panel-5951)
* [  TypeScript ](#tab-panel-5952)

**JavaScript**

```js
class MyAgent extends Agent {
  async onEmail(email) {
    await this.replyToEmail(email, {
      fromName: "Support Bot", // Display name for the sender
      subject: "Re: Your inquiry", // Optional, defaults to "Re: "
      body: "Thanks for contacting us!", // Email body
      contentType: "text/plain", // Optional, defaults to "text/plain"
      headers: {
        // Optional custom headers
        "X-Custom-Header": "value",
      },
      secret: this.env.EMAIL_SECRET, // Optional, signs headers for secure reply routing
    });
  }
}
```

**TypeScript**

```ts
class MyAgent extends Agent {
  async onEmail(email: AgentEmail) {
    await this.replyToEmail(email, {
      fromName: "Support Bot", // Display name for the sender
      subject: "Re: Your inquiry", // Optional, defaults to "Re: "
      body: "Thanks for contacting us!", // Email body
      contentType: "text/plain", // Optional, defaults to "text/plain"
      headers: {
        // Optional custom headers
        "X-Custom-Header": "value",
      },
      secret: this.env.EMAIL_SECRET, // Optional, signs headers for secure reply routing
    });
  }
}
```

### Deferred replies

`replyToEmail()` requires a live `AgentEmail` object, so it only works inside `onEmail()`. If you need to reply later — from a scheduled task, a callable method, or after a human-in-the-loop approval — store the sender info in state and use `sendEmail()`:

* [  JavaScript ](#tab-panel-5963)
* [  TypeScript ](#tab-panel-5964)

**JavaScript**

```js
class MyAgent extends Agent {
  async onEmail(email) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    this.setState({
      ...this.state,
      pendingReply: {
        to: email.from,
        messageId: parsed.messageId,
        subject: parsed.subject,
      },
    });
  }


  @callable()
  async sendDelayedReply(body) {
    const { pendingReply } = this.state;
    if (!pendingReply) return;


    await this.sendEmail({
      binding: this.env.EMAIL,
      to: pendingReply.to,
      from: "support@yourdomain.com",
      subject: `Re: ${pendingReply.subject}`,
      text: body,
      inReplyTo: pendingReply.messageId,
      secret: this.env.EMAIL_SECRET,
    });
  }
}
```

**TypeScript**

```ts
class MyAgent extends Agent {
  async onEmail(email: AgentEmail) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    this.setState({
      ...this.state,
      pendingReply: {
        to: email.from,
        messageId: parsed.messageId,
        subject: parsed.subject,
      },
    });
  }


  @callable()
  async sendDelayedReply(body: string) {
    const { pendingReply } = this.state;
    if (!pendingReply) return;


    await this.sendEmail({
      binding: this.env.EMAIL,
      to: pendingReply.to,
      from: "support@yourdomain.com",
      subject: `Re: ${pendingReply.subject}`,
      text: body,
      inReplyTo: pendingReply.messageId,
      secret: this.env.EMAIL_SECRET,
    });
  }
}
```

The `inReplyTo` field sets the `In-Reply-To` header so mail clients thread the reply correctly. The `secret` signs the agent routing headers so that follow-up replies route back to this agent instance via `createSecureReplyEmailResolver`.

### Forwarding emails

* [  JavaScript ](#tab-panel-5947)
* [  TypeScript ](#tab-panel-5948)

**JavaScript**

```js
class MyAgent extends Agent {
  async onEmail(email) {
    await email.forward("admin@example.com");
  }
}
```

**TypeScript**

```ts
class MyAgent extends Agent {
  async onEmail(email: AgentEmail) {
    await email.forward("admin@example.com");
  }
}
```

### Rejecting emails

* [  JavaScript ](#tab-panel-5953)
* [  TypeScript ](#tab-panel-5954)

**JavaScript**

```js
class MyAgent extends Agent {
  async onEmail(email) {
    if (isSpam(email)) {
      email.setReject("Message rejected as spam");
      return;
    }
    // Process the email...
  }
}
```

**TypeScript**

```ts
class MyAgent extends Agent {
  async onEmail(email: AgentEmail) {
    if (isSpam(email)) {
      email.setReject("Message rejected as spam");
      return;
    }
    // Process the email...
  }
}
```

## Error handling

When sending emails via `sendEmail()` or `replyToEmail()`, handle these common errors:

* [  JavaScript ](#tab-panel-5965)
* [  TypeScript ](#tab-panel-5966)

**JavaScript**

```js
class MyAgent extends Agent {
  async onEmail(email) {
    try {
      await this.replyToEmail(email, {
        fromName: "Support Bot",
        body: "Thanks for your email!",
      });
    } catch (error) {
      switch (error.code) {
        case "E_SENDER_NOT_VERIFIED":
          console.error("Sender domain not verified. Verify in dashboard.");
          break;
        case "E_RATE_LIMIT_EXCEEDED":
          console.error("Rate limit exceeded. Back off and retry.");
          break;
        case "E_DAILY_LIMIT_EXCEEDED":
          console.error("Daily sending quota reached.");
          break;
        case "E_CONTENT_TOO_LARGE":
          console.error("Email content exceeds size limit.");
          break;
        default:
          console.error("Email sending failed:", error.message);
      }
    }
  }
}
```

**TypeScript**

```ts
class MyAgent extends Agent {
  async onEmail(email: AgentEmail) {
    try {
      await this.replyToEmail(email, {
        fromName: "Support Bot",
        body: "Thanks for your email!",
      });
    } catch (error) {
      switch (error.code) {
        case "E_SENDER_NOT_VERIFIED":
          console.error("Sender domain not verified. Verify in dashboard.");
          break;
        case "E_RATE_LIMIT_EXCEEDED":
          console.error("Rate limit exceeded. Back off and retry.");
          break;
        case "E_DAILY_LIMIT_EXCEEDED":
          console.error("Daily sending quota reached.");
          break;
        case "E_CONTENT_TOO_LARGE":
          console.error("Email content exceeds size limit.");
          break;
        default:
          console.error("Email sending failed:", error.message);
      }
    }
  }
}
```

### Common error codes

| Error Code                 | Description                        | Solution                             |
| -------------------------- | ---------------------------------- | ------------------------------------ |
| E\_SENDER\_NOT\_VERIFIED   | Sender domain/address not verified | Verify in Cloudflare dashboard       |
| E\_RATE\_LIMIT\_EXCEEDED   | Sending rate limit reached         | Implement exponential backoff        |
| E\_DAILY\_LIMIT\_EXCEEDED  | Daily quota exceeded               | Wait for quota reset or upgrade plan |
| E\_CONTENT\_TOO\_LARGE     | Email exceeds size limit           | Reduce attachments or content        |
| E\_RECIPIENT\_NOT\_ALLOWED | Recipient not in allowed list      | Check allowed destination addresses  |
| E\_RECIPIENT\_SUPPRESSED   | Recipient is on suppression list   | Remove from suppression list         |
| E\_VALIDATION\_ERROR       | Invalid email format               | Check email addresses                |
| E\_TOO\_MANY\_RECIPIENTS   | More than 50 recipients            | Split into multiple sends            |

## Secure reply routing

When your agent sends emails and expects replies, use secure reply routing to prevent attackers from forging headers to route emails to arbitrary agent instances.

### How it works

1. **Outbound:** When you call `replyToEmail()` or `sendEmail()` with a `secret`, the agent signs the routing headers (`X-Agent-Name`, `X-Agent-ID`) using HMAC-SHA256.
2. **Inbound:** `createSecureReplyEmailResolver` verifies the signature before routing.
3. **Enforcement:** If an email was routed via the secure resolver, `replyToEmail()` requires a secret (or explicit `null` to opt-out).

### Setup

1. Add a secret to your Worker:

  * [  wrangler.jsonc ](#tab-panel-5933)
  * [  wrangler.toml ](#tab-panel-5934)

**JSONC**  
```jsonc  
{  
  "$schema": "./node_modules/wrangler/config-schema.json",  
  "vars": {  
    "EMAIL_SECRET": "change-me-in-production"  
  }  
}  
```

**TOML**  
```toml  
[vars]  
EMAIL_SECRET = "change-me-in-production"  
```  
For production, use Wrangler secrets instead:  
```sh  
npx wrangler secret put EMAIL_SECRET  
```
2. Use the combined resolver pattern:

  * [  JavaScript ](#tab-panel-5961)
  * [  TypeScript ](#tab-panel-5962)

**JavaScript**  
```js  
export default {  
  async email(message, env) {  
    const secureReplyResolver = createSecureReplyEmailResolver(  
      env.EMAIL_SECRET,  
    );  
    const addressResolver = createAddressBasedEmailResolver("EmailAgent");  
    await routeAgentEmail(message, env, {  
      resolver: async (email, env) => {  
        const replyRouting = await secureReplyResolver(email, env);  
        if (replyRouting) return replyRouting;  
        return addressResolver(email, env);  
      },  
    });  
  },  
};  
```

**TypeScript**  
```ts  
export default {  
 async email(message, env) {  
  const secureReplyResolver = createSecureReplyEmailResolver(  
   env.EMAIL_SECRET,  
  );  
  const addressResolver = createAddressBasedEmailResolver("EmailAgent");  
  await routeAgentEmail(message, env, {  
   resolver: async (email, env) => {  
    const replyRouting = await secureReplyResolver(email, env);  
    if (replyRouting) return replyRouting;  
    return addressResolver(email, env);  
   },  
  });  
 },  
} satisfies ExportedHandler<Env>;  
```
3. Sign outbound emails:

  * [  JavaScript ](#tab-panel-5959)
  * [  TypeScript ](#tab-panel-5960)

**JavaScript**  
```js  
class MyAgent extends Agent {  
  async onEmail(email) {  
    await this.replyToEmail(email, {  
      fromName: "My Agent",  
      body: "Thanks for your email!",  
      secret: this.env.EMAIL_SECRET, // Signs the routing headers  
    });  
  }  
}  
```

**TypeScript**  
```ts  
class MyAgent extends Agent {  
 async onEmail(email: AgentEmail) {  
  await this.replyToEmail(email, {  
   fromName: "My Agent",  
   body: "Thanks for your email!",  
   secret: this.env.EMAIL_SECRET, // Signs the routing headers  
  });  
 }  
}  
```

### Enforcement behavior

When an email is routed via `createSecureReplyEmailResolver`, the `replyToEmail()` method enforces signing:

| secret value        | Behavior                                                     |
| ------------------- | ------------------------------------------------------------ |
| "my-secret"         | Signs headers (secure)                                       |
| undefined (omitted) | **Throws error** \- must provide secret or explicit opt-out  |
| null                | Allowed but not recommended - explicitly opts out of signing |

## Complete example

Here is a complete Email Service agent that sends outbound mail and handles secure replies:

* [  JavaScript ](#tab-panel-5967)
* [  TypeScript ](#tab-panel-5968)

**JavaScript**

```js
import { Agent, callable, routeAgentEmail } from "agents";
import {
  createAddressBasedEmailResolver,
  createSecureReplyEmailResolver,
} from "agents/email";
import PostalMime from "postal-mime";


export class EmailAgent extends Agent {
  @callable()
  async sendWelcome(to) {
    return this.sendEmail({
      binding: this.env.EMAIL,
      to,
      from: "support@yourdomain.com",
      subject: "Welcome!",
      text: "Thanks for signing up.",
      secret: this.env.EMAIL_SECRET,
    });
  }


  async onEmail(email) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    console.log(`Email from ${email.from}: ${parsed.subject}`);


    const emails = this.state.emails || [];
    emails.push({
      from: email.from,
      subject: parsed.subject,
      receivedAt: new Date().toISOString(),
    });
    this.setState({ ...this.state, emails });


    await this.replyToEmail(email, {
      fromName: "Support Bot",
      body: `Thanks for your email! We received: "${parsed.subject}"`,
      secret: this.env.EMAIL_SECRET,
    });
  }
}


export default {
  async email(message, env) {
    const secureReplyResolver = createSecureReplyEmailResolver(
      env.EMAIL_SECRET,
      {
        maxAge: 7 * 24 * 60 * 60, // 7 days
        onInvalidSignature: (email, reason) => {
          console.warn(`Invalid signature from ${email.from}: ${reason}`);
        },
      },
    );
    const addressResolver = createAddressBasedEmailResolver("EmailAgent");


    await routeAgentEmail(message, env, {
      resolver: async (email, env) => {
        const replyRouting = await secureReplyResolver(email, env);
        if (replyRouting) return replyRouting;
        return addressResolver(email, env);
      },
      onNoRoute: (email) => {
        console.warn(`No route found for email from ${email.from}`);
        email.setReject("Unknown recipient");
      },
    });
  },
};
```

**TypeScript**

```ts
import { Agent, callable, routeAgentEmail } from "agents";
import {
  createAddressBasedEmailResolver,
  createSecureReplyEmailResolver,
  type AgentEmail,
} from "agents/email";
import PostalMime from "postal-mime";


interface Env {
  EmailAgent: DurableObjectNamespace<EmailAgent>;
  EMAIL: SendEmail;
  EMAIL_SECRET: string;
}


export class EmailAgent extends Agent<Env> {
  @callable()
  async sendWelcome(to: string) {
    return this.sendEmail({
      binding: this.env.EMAIL,
      to,
      from: "support@yourdomain.com",
      subject: "Welcome!",
      text: "Thanks for signing up.",
      secret: this.env.EMAIL_SECRET,
    });
  }


  async onEmail(email: AgentEmail) {
    const raw = await email.getRaw();
    const parsed = await PostalMime.parse(raw);


    console.log(`Email from ${email.from}: ${parsed.subject}`);


    const emails = this.state.emails || [];
    emails.push({
      from: email.from,
      subject: parsed.subject,
      receivedAt: new Date().toISOString(),
    });
    this.setState({ ...this.state, emails });


    await this.replyToEmail(email, {
      fromName: "Support Bot",
      body: `Thanks for your email! We received: "${parsed.subject}"`,
      secret: this.env.EMAIL_SECRET,
    });
  }
}


export default {
  async email(message, env: Env) {
    const secureReplyResolver = createSecureReplyEmailResolver(
      env.EMAIL_SECRET,
      {
        maxAge: 7 * 24 * 60 * 60, // 7 days
        onInvalidSignature: (email, reason) => {
          console.warn(`Invalid signature from ${email.from}: ${reason}`);
        },
      },
    );
    const addressResolver = createAddressBasedEmailResolver("EmailAgent");


    await routeAgentEmail(message, env, {
      resolver: async (email, env) => {
        const replyRouting = await secureReplyResolver(email, env);
        if (replyRouting) return replyRouting;
        return addressResolver(email, env);
      },
      onNoRoute: (email) => {
        console.warn(`No route found for email from ${email.from}`);
        email.setReject("Unknown recipient");
      },
    });
  },
} satisfies ExportedHandler<Env>;
```

## API reference

### `EmailAddress`

**TypeScript**

```ts
interface EmailAddress {
  email: string;
  name?: string;
}
```

### `sendEmail`

**TypeScript**

```ts
async sendEmail(options: {
  binding: EmailSendBinding;
  to: string | EmailAddress | (string | EmailAddress)[];
  from: string | EmailAddress;
  subject: string;
  text?: string;
  html?: string;
  replyTo?: string | EmailAddress;
  cc?: string | EmailAddress | (string | EmailAddress)[];
  bcc?: string | EmailAddress | (string | EmailAddress)[];
  inReplyTo?: string;
  headers?: Record<string, string>;
  secret?: string;
}): Promise<EmailSendResult>;
```

Send an outbound email through the Email Service binding. Automatically injects `X-Agent-Name` and `X-Agent-ID` headers. When `secret` is provided, signs headers with HMAC-SHA256 for secure reply routing.

| Option    | Description                                                               |
| --------- | ------------------------------------------------------------------------- |
| binding   | The send\_email binding (for example, this.env.EMAIL). Required.          |
| to        | Recipient address, array of addresses, or EmailAddress object(s)          |
| from      | Sender address or EmailAddress object                                     |
| subject   | Email subject line                                                        |
| text      | Plain text body (at least one of text/html required)                      |
| html      | HTML body (at least one of text/html required)                            |
| replyTo   | Reply-to address or EmailAddress object                                   |
| cc        | CC recipient address, array of addresses, or EmailAddress object(s)       |
| bcc       | BCC recipient address, array of addresses, or EmailAddress object(s)      |
| inReplyTo | Message-ID for threading (sets the In-Reply-To header)                    |
| headers   | Additional custom headers (agent headers take precedence if they collide) |
| secret    | Secret for HMAC signing of agent routing headers                          |

### `routeAgentEmail`

**TypeScript**

```ts
function routeAgentEmail<Env>(
  email: ForwardableEmailMessage,
  env: Env,
  options: {
    resolver: EmailResolver;
    onNoRoute?: (email: ForwardableEmailMessage) => void | Promise<void>;
  },
): Promise<void>;
```

Routes an incoming email to the appropriate Agent based on the resolver's decision.

| Option    | Description                                                                                                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| resolver  | Function that determines which agent to route the email to                                                                                                                              |
| onNoRoute | Optional callback invoked when no routing information is found. Use this to reject the email or perform custom handling. If not provided, a warning is logged and the email is dropped. |

### `createSecureReplyEmailResolver`

**TypeScript**

```ts
function createSecureReplyEmailResolver(
  secret: string,
  options?: {
    maxAge?: number;
    onInvalidSignature?: (
      email: ForwardableEmailMessage,
      reason: SignatureFailureReason,
    ) => void;
  },
): EmailResolver;


type SignatureFailureReason =
  | "missing_headers"
  | "expired"
  | "invalid"
  | "malformed_timestamp";
```

Creates a resolver for routing email replies with signature verification.

| Option             | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| secret             | Secret key for HMAC verification (must match the key used to sign)       |
| maxAge             | Maximum age of signature in seconds (default: 30 days / 2592000 seconds) |
| onInvalidSignature | Optional callback for logging when signature verification fails          |

### `signAgentHeaders`

**TypeScript**

```ts
function signAgentHeaders(
  secret: string,
  agentName: string,
  agentId: string,
): Promise<Record<string, string>>;
```

Manually sign agent routing headers. Returns an object with `X-Agent-Name`, `X-Agent-ID`, `X-Agent-Sig`, and `X-Agent-Sig-Ts` headers.

Useful when sending emails through external services while maintaining secure reply routing. The signature includes a timestamp and will be valid for 30 days by default.

## Next steps

[ HTTP and SSE ](https://edgetunnel-b2h.pages.dev/agents/runtime/communication/http-sse/) Handle HTTP requests in your Agent. 

[ Webhooks ](https://edgetunnel-b2h.pages.dev/agents/communication-channels/webhooks/) Receive events from external services. 

[ Agents API ](https://edgetunnel-b2h.pages.dev/agents/runtime/agents-api/) Complete API reference for the Agents SDK.

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://edgetunnel-b2h.pages.dev/agents/examples/email-agent/#page","headline":"Email agent · Cloudflare Agents docs","description":"Build an agent that sends, receives, routes, and replies to email using Cloudflare Email Service and the Agents SDK.","url":"https://edgetunnel-b2h.pages.dev/agents/examples/email-agent/","inLanguage":"en","image":"https://edgetunnel-b2h.pages.dev/dev-products-preview.png","dateModified":"2026-06-09","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://edgetunnel-b2h.pages.dev/#website","name":"Cloudflare Docs","url":"https://edgetunnel-b2h.pages.dev/"}}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/agents/","name":"Agents"}},{"@type":"ListItem","position":3,"item":{"@id":"/agents/examples/","name":"Examples"}},{"@type":"ListItem","position":4,"item":{"@id":"/agents/examples/email-agent/","name":"Email agent"}}]}
```