AgenticEmail: AI 代理的电子邮件
AgenticEmail 为代理提供一个真实、可寻址的电子邮箱(收件箱)供其拥有。与仅能外发的发送 API 不同,每个收件箱既能发送也能接收邮件:入站邮件通过 Webhook 或 WebSocket 流以解析后的 JSON 格式到达。当代理需要通过电子邮件地址被联系(而不仅仅是能够发送邮件)时,就可以使用此技能。
常见的触发场景包括:代理需要注册第三方服务、接收验证码或 OTP、通过邮件接收通知、运行支持或外联工作流,或者与人或其他代理交换电子邮件。
设置
- 在 https://app.agenticemail.dev 获取一个 API 密钥(以
am_开头)。免费套餐包含真实的收件箱、发送、接收和 Webhook 功能。 - 导出密钥:
export AGENTICEMAIL_API_KEY=am_... - 从下面选择一个集成路径。所有路径都调用
https://api.agenticemail.dev。
选择路径
- 托管 MCP 服务器(推荐用于支持 MCP 的代理,如 Claude、Cursor 和 Vercel AI SDK)。 使用 API 密钥作为 Bearer 令牌连接
https://api.agenticemail.dev/mcp。代理将直接获得以下工具:create_inbox、list_inboxes、list_threads、get_thread、list_messages、get_message、send_message、reply_to_message。 - CLI(
npm i -g agenticemail-cli),适用于 Shell 驱动的代理。 - SDK(适用于 TypeScript 的
npm i agenticemail,或适用于 Python 的pip install 'agenticemail[e2e]'),适用于代码集成。
MCP 客户端配置
对于支持 HTTP 的客户端(Claude、Cursor 以及其他支持流式 HTTP 的客户端):
{
"mcpServers": {
"agenticemail": {
"type": "http",
"url": "https://api.agenticemail.dev/mcp",
"headers": { "Authorization": "Bearer ${AGENTICEMAIL_API_KEY}" }
}
}
}
对于仅支持 stdio 的客户端,通过桥接方式连接:
npx mcp-remote https://api.agenticemail.dev/mcp \
--header "Authorization: Bearer $AGENTICEMAIL_API_KEY"
核心流程:创建、发送、接收、回复
CLI:
INBOX=$(agenticemail inboxes create --username assistant | jq -r .id)
agenticemail messages send "$INBOX" --to [email protected] \
--subject "Hello" --text "Sent by an agent."
agenticemail messages list "$INBOX" --limit 5
agenticemail messages reply "$INBOX" <msgId> --text "On it."
agenticemail wait-for-message "$INBOX" --timeout 300
TypeScript SDK:
import { AgenticEmail } from "agenticemail";
const client = new AgenticEmail({ apiKey: process.env.AGENTICEMAIL_API_KEY! });
const inbox = await client.inboxes.create({ username: "assistant" });
await client.messages.send(inbox.id, {
to: ["[email protected]"],
subject: "Hello",
text: "Sent by an agent.",
});
const { data } = await client.messages.list(inbox.id, { limit: 5 });
const msg = await client.messages.get(inbox.id, data[0].id);
await client.messages.reply(inbox.id, msg.id, { text: "Thanks." });
Python SDK:
from agenticemail import AgenticEmail
client = AgenticEmail(api_key=os.environ["AGENTICEMAIL_API_KEY"])
inbox = client.inboxes.create(username="assistant")
client.messages.send(inbox.id, to=["[email protected]"], subject="Hello", text="...")
for m in client.messages.list(inbox.id, limit=5).data:
print(m.subject)
REST API(如果你不使用 SDK)
基础 URL 为 https://api.agenticemail.dev,请求头为 Authorization: Bearer $AGENTICEMAIL_API_KEY。
| 方法 | 路径 | 目的 |
|---|---|---|
| POST | /v1/inboxes | 创建收件箱。请求体 { "username": "assistant" }(可选)。 |
| GET | /v1/inboxes | 列出收件箱。 |
| POST | /v1/inboxes/{id}/messages | 发送邮件。请求体 { "to": ["[email protected]"], "subject": "...", "text": "..." }。 |
| GET | /v1/inboxes/{id}/messages | 列出邮件。查询参数 limit、cursor。 |
| GET | /v1/inboxes/{id}/messages/{msgId} | 获取一封已解析的邮件。 |
| POST | /v1/inboxes/{id}/messages/{msgId}/reply | 在同一个线程中回复。 |
| POST | /v1/webhooks | 注册一个 Webhook。请求体 { "url": "...", "eventTypes": ["message.received"] }。 |
每个邮件对象都包含一个 encrypted 布尔值,以便客户端知道是否需要解密。
接收入站邮件
注册一个 Webhook,以便新邮件到达时立即通知代理:
agenticemail webhooks create --url https://your-app/hook \
--event-types message.received
每个事件都会携带已解析的发送者、主题、文本、HTML 和附件。如果代理已经在运行,还可以使用 WebSocket 流接收相同的事件(agenticemail events tail)。
端到端加密(可选)
对于代理之间的邮件,AgenticEmail 提供可选的端到端加密:私钥在客户端(SDK 或 CLI)生成并保存,绝不会存储在服务器上,因此平台无法读取内容。在 CLI 中,使用 agenticemail keys generate <inbox> 然后 agenticemail keys publish <inbox> 来启用加密,之后 messages send 和 messages get 会自动加密和解密。在 SDK 中,在构造客户端时传递一个 e2e 身份:
import { AgenticEmail, generateIdentity } from "agenticemail";
const client = new AgenticEmail({
apiKey: process.env.AGENTICEMAIL_API_KEY!,
e2e: { identity: generateIdentity(), autoPublish: true },
});
以下是对其功能范围的诚实说明:
- 此功能是可选加入的,并且仅在两个都已发布密钥的 AgenticEmail 收件箱之间有效。默认情况下是纯文本。
- 私钥仅在客户端,绝不会到达服务器,因此平台或其云提供商都无法读取加密内容。
- 发送到外部地址(如 Gmail 或企业邮箱服务器)会回退到纯文本,因为没有可加密的公钥。
- 路由元数据(发件人、收件人、时间、大小)仍然是可见的,这是 SMTP 协议的要求。
- 如果丢失了私钥,旧的加密邮件将无法恢复。这是服务器不保存私钥的代价。