Agents 可通过 Cloudflare Email Service 发送和接收邮件。本指南展示如何使用 Workers 绑定发送出站邮件、将入站邮件路由到 Agent,并安全处理后续回复。
在 Agent 中使用邮件前,你需要:
- 已在 Cloudflare Email Service 中接入的域名。
- 在
wrangler.jsonc中配置send_email绑定,用于出站邮件。 - Email Service 路由规则,将入站邮件发送到 Worker。
- 可选:若需安全回复路由,配置
EMAIL_SECRETsecret。
- 登录 Cloudflare 仪表板 ↗。
- 前往 Compute & AI(计算与 AI) > Email Service。
- 选择 Onboard Domain(接入域名) 并选择你的域名。
- 添加 DNS 记录(SPF 与 DKIM)以授权发送。
DNS 变更通常在 5–15 分钟内完成(使用 Cloudflare DNS 的域名),但全球传播最多可能需要 24 小时。
向 Worker 添加 email binding:
{
"$schema": "./node_modules/wrangler/config-schema.json",
"send_email": [
{
"name": "EMAIL",
"remote": true
}
]
}[[send_email]]
name = "EMAIL"
remote = trueremote = true 选项让你在 wrangler dev 本地开发期间调用真实的 Email Service API。
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: "[email protected]",
replyTo: "[email protected]",
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"),
});
},
};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: "[email protected]",
replyTo: "[email protected]",
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>;sendEmail() 通过你显式传入的 send_email 绑定发送出站邮件。它会自动向每条消息注入 Agent 路由头(X-Agent-Name、X-Agent-ID),并可选择用 HMAC-SHA256 签名,以便回复能路由回同一 Agent 实例。
class MyAgent extends Agent {
@callable()
async sendReceipt(to, orderId) {
const result = await this.sendEmail({
binding: this.env.EMAIL,
to,
from: { email: "[email protected]", name: "Billing Bot" },
replyTo: "[email protected]",
subject: `Receipt for order ${orderId}`,
text: `Your receipt for order ${orderId} is ready.`,
secret: this.env.EMAIL_SECRET,
});
return result.messageId;
}
}class MyAgent extends Agent {
@callable()
async sendReceipt(to: string, orderId: string) {
const result = await this.sendEmail({
binding: this.env.EMAIL,
to,
from: { email: "[email protected]", name: "Billing Bot" },
replyTo: "[email protected]",
subject: `Receipt for order ${orderId}`,
text: `Your receipt for order ${orderId} is ready.`,
secret: this.env.EMAIL_SECRET,
});
return result.messageId;
}
}提供 secret 时,Agent 会签名路由头,使经 createSecureReplyEmailResolver 验证的回复能路由回同一 Agent 实例。
若希望收件人继续与同一 Agent 对话,将 replyTo 设为会路由回 Worker 的邮箱。
Resolver 决定哪一 Agent 实例接收入站邮件。按用例选择合适的 resolver。
对于基本的 Email Service 收发,createAddressBasedEmailResolver() 已足够。下文的安全回复 resolver 是可选的,专用于 Agents SDK 回复签名,并非 Email Service 的硬性要求。
推荐用于入站邮件。根据收件地址路由邮件。
import { createAddressBasedEmailResolver } from "agents/email";
const resolver = createAddressBasedEmailResolver("EmailAgent");import { createAddressBasedEmailResolver } from "agents/email";
const resolver = createAddressBasedEmailResolver("EmailAgent");路由逻辑:
| 收件地址 | Agent 名称 | Agent ID |
|---|---|---|
[email protected] |
EmailAgent(默认) |
support |
[email protected] |
EmailAgent(默认) |
sales |
[email protected] |
NotificationAgent |
user123 |
子地址格式(agent+id@domain)允许从单一邮件域名路由到不同 Agent 命名空间与实例。
用于带签名验证的回复流程。验证入站邮件是否为对你出站邮件的真实回复,防止攻击者伪造头将邮件路由到任意 Agent 实例。
import { createSecureReplyEmailResolver } from "agents/email";
const resolver = createSecureReplyEmailResolver(env.EMAIL_SECRET);import { createSecureReplyEmailResolver } from "agents/email";
const resolver = createSecureReplyEmailResolver(env.EMAIL_SECRET);当 Agent 使用 replyToEmail() 或 sendEmail() 并传入 secret 发送邮件时,会用时间戳签名路由头。回复返回时,此 resolver 在路由前验证签名并检查是否过期。
选项:
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"
},
});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"
},
});适用场景: Agent 发起邮件对话且需要回复安全路由回同一 Agent 实例时。
用于单实例路由。无论收件地址为何,都将所有邮件路由到指定 Agent 实例。
import { createCatchAllEmailResolver } from "agents/email";
const resolver = createCatchAllEmailResolver("EmailAgent", "default");import { createCatchAllEmailResolver } from "agents/email";
const resolver = createCatchAllEmailResolver("EmailAgent", "default");适用场景: 单一 Agent 实例处理所有邮件时(例如共享收件箱)。
可组合多个 resolver 处理不同场景:
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");
},
});
},
};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>;调用 Agent 的 onEmail 方法时,会收到 AgentEmail 对象:
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
};使用 postal-mime ↗ 等库解析原始邮件:
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);
}
}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);
}
}使用 isAutoReplyEmail() 检测自动回复,避免邮件循环:
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...
}
}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...
}
}这会检查标准 RFC 3834 头(Auto-Submitted、X-Auto-Response-Suppress、Precedence),判断邮件是否为自动回复。
使用 this.replyToEmail() 通过入站邮件的回复通道发送回复:
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
});
}
}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
});
}
}replyToEmail() 需要实时的 AgentEmail 对象,因此只能在 onEmail() 内使用。若需稍后回复——例如定时任务、callable 方法或人工审批后——将发件人信息存入 state 并使用 sendEmail():
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: "[email protected]",
subject: `Re: ${pendingReply.subject}`,
text: body,
inReplyTo: pendingReply.messageId,
secret: this.env.EMAIL_SECRET,
});
}
}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: "[email protected]",
subject: `Re: ${pendingReply.subject}`,
text: body,
inReplyTo: pendingReply.messageId,
secret: this.env.EMAIL_SECRET,
});
}
}inReplyTo 字段设置 In-Reply-To 头,使邮件客户端正确串接回复线程。secret 签名 Agent 路由头,使后续回复经 createSecureReplyEmailResolver 路由回此 Agent 实例。
class MyAgent extends Agent {
async onEmail(email) {
await email.forward("[email protected]");
}
}class MyAgent extends Agent {
async onEmail(email: AgentEmail) {
await email.forward("[email protected]");
}
}class MyAgent extends Agent {
async onEmail(email) {
if (isSpam(email)) {
email.setReject("Message rejected as spam");
return;
}
// Process the email...
}
}class MyAgent extends Agent {
async onEmail(email: AgentEmail) {
if (isSpam(email)) {
email.setReject("Message rejected as spam");
return;
}
// Process the email...
}
}通过 sendEmail() 或 replyToEmail() 发送邮件时,请处理以下常见错误:
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);
}
}
}
}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);
}
}
}
}| 错误码 | 描述 | 解决方案 |
|---|---|---|
E_SENDER_NOT_VERIFIED |
发件人域名/地址未验证 | 在 Cloudflare 仪表板中验证 |
E_RATE_LIMIT_EXCEEDED |
达到发送速率限制 | 实现指数退避 |
E_DAILY_LIMIT_EXCEEDED |
超出每日配额 | 等待配额重置或升级套餐 |
E_CONTENT_TOO_LARGE |
邮件超出大小限制 | 减少附件或内容 |
E_RECIPIENT_NOT_ALLOWED |
收件人不在允许列表 | 检查允许的目标地址 |
E_RECIPIENT_SUPPRESSED |
收件人在抑制列表 | 从抑制列表移除 |
E_VALIDATION_ERROR |
邮件格式无效 | 检查邮箱地址 |
E_TOO_MANY_RECIPIENTS |
超过 50 个收件人 | 拆分为多次发送 |
当 Agent 发送邮件并期望收到回复时,使用安全回复路由,防止攻击者伪造头将邮件路由到任意 Agent 实例。
- 出站: 调用
replyToEmail()或sendEmail()并传入secret时,Agent 使用 HMAC-SHA256 签名路由头(X-Agent-Name、X-Agent-ID)。 - 入站:
createSecureReplyEmailResolver在路由前验证签名。 - 强制要求: 如果电子邮件是通过安全解析器路由的,
replyToEmail()必须提供 secret(或显式传入null以选择退出)。
-
将签名密钥存储为 Wrangler secret。不要将它放入
vars,也不要提交到源码管理系统:npx wrangler secret put EMAIL_SECRETyarn wrangler secret put EMAIL_SECRETpnpm wrangler secret put EMAIL_SECRET -
使用组合 resolver 模式:
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); }, }); }, };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>; -
对出站邮件签名:
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 }); } }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 }); } }
当邮件经 createSecureReplyEmailResolver 路由时,replyToEmail() 会强制签名:
secret 值 |
行为 |
|---|---|
"my-secret" |
签名头(安全) |
undefined(省略) |
抛出错误 — 必须提供 secret 或显式选择退出 |
null |
允许但不推荐 — 显式选择不签名 |
以下是一个完整的 Email Service Agent,可发送出站邮件并处理安全回复:
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: "[email protected]",
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");
},
});
},
};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: "[email protected]",
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>;interface EmailAddress {
email: string;
name?: string;
}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>;通过 Email Service 绑定发送出站邮件。自动注入 X-Agent-Name 与 X-Agent-ID 头。提供 secret 时,用 HMAC-SHA256 签名头以实现安全回复路由。
| 选项 | 描述 |
|---|---|
binding |
send_email 绑定(例如 this.env.EMAIL)。必需。 |
to |
收件地址、地址数组或 EmailAddress 对象 |
from |
发件地址或 EmailAddress 对象 |
subject |
邮件主题 |
text |
纯文本正文(text/html 至少填一项) |
html |
HTML 正文(text/html 至少填一项) |
replyTo |
回复地址或 EmailAddress 对象 |
cc |
抄送地址、地址数组或 EmailAddress 对象 |
bcc |
密送地址、地址数组或 EmailAddress 对象 |
inReplyTo |
用于串接的 Message-ID(设置 In-Reply-To 头) |
headers |
额外自定义头(与 Agent 头冲突时以 Agent 头为准) |
secret |
用于 HMAC 签名 Agent 路由头的 secret |
function routeAgentEmail<Env>(
email: ForwardableEmailMessage,
env: Env,
options: {
resolver: EmailResolver;
onNoRoute?: (email: ForwardableEmailMessage) => void | Promise<void>;
},
): Promise<void>;根据 resolver 决策,将入站邮件路由到相应 Agent。
| 选项 | 描述 |
|---|---|
resolver |
决定邮件路由到哪个 Agent 的函数 |
onNoRoute |
可选回调,未找到路由信息时调用。可用于拒收或自定义处理。未提供时记录警告并丢弃邮件。 |
function createSecureReplyEmailResolver(
secret: string,
options?: {
maxAge?: number;
onInvalidSignature?: (
email: ForwardableEmailMessage,
reason: SignatureFailureReason,
) => void;
},
): EmailResolver;
type SignatureFailureReason =
| "missing_headers"
| "expired"
| "invalid"
| "malformed_timestamp";创建带签名验证的回复路由 resolver。
| 选项 | 描述 |
|---|---|
secret |
HMAC 验证密钥(须与签名时使用的密钥一致) |
maxAge |
签名最大有效期(秒)(默认:30 天 / 2592000 秒) |
onInvalidSignature |
签名验证失败时的可选日志回调 |
function signAgentHeaders(
secret: string,
agentName: string,
agentId: string,
): Promise<Record<string, string>>;手动签名 Agent 路由头。返回包含 X-Agent-Name、X-Agent-ID、X-Agent-Sig、X-Agent-Sig-Ts 的对象。
适用于通过外部服务发送邮件同时保持安全回复路由。签名含时间戳,默认 30 天内有效。