智能邮件代理

agentmail

分类编程

作者Agentic Awesome Skills 社区

许可MIT

评分4.60/5

使用13.7K

AgentMail — AI Agent 专用邮箱

AgentMail 通过 REST API 为 AI Agent 提供真实的电子邮件地址 (@theagentmail.net)。Agent 可以发送和接收邮件，注册服务（如 GitHub、AWS、Slack 等）并获取验证码。内置的 Karma 系统可防止垃圾邮件，确保共享域名的信誉度。

Base URL: https://api.theagentmail.net

使用场景

AI Agent 需要真实的收件箱/发件箱用于注册、验证流程或事务性通信。

需要配置 AgentMail 账户、发送消息、读取收件箱内容或注册入站 Webhook。

需要监控 Karma 使用情况或将邮件事件接入 Agent 自动化流程。

快速上手

所有请求均需在 Header 中包含 Authorization: Bearer am_...（API 密钥可从控制面板获取）。

创建电子邮件账户 (-10 karma)

bash

curl -X POST https://api.theagentmail.net/v1/accounts \
  -H "Authorization: Bearer am_..." \
  -H "Content-Type: application/json" \
  -d '{"address": "[email protected]"}'

响应：{"data": {"id": "...", "address": "[email protected]", "displayName": null, "createdAt": 123}}

发送邮件 (-1 karma)

bash

curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/messages \
  -H "Authorization: Bearer am_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["[email protected]"],
    "subject": "Hello from my agent",
    "text": "Plain text body",
    "html": "<p>Optional HTML body</p>"
  }'

可选字段：cc、bcc（字符串数组）、inReplyTo、references（用于邮件线程的字符串）、attachments（包含 {filename, contentType, content} 的数组，其中 content 为 base64 编码）。

读取收件箱

bash

# 列出消息
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages \
  -H "Authorization: Bearer am_..."
获取完整消息（包含正文和附件）
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId} \
  -H "Authorization: Bearer am_..."

查询 Karma 余额

bash

curl https://api.theagentmail.net/v1/karma \
  -H "Authorization: Bearer am_..."

响应：{"data": {"balance": 90, "events": [...]}}

注册 Webhook（实时入站通知）

bash

curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/webhooks \
  -H "Authorization: Bearer am_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://my-agent.example.com/inbox"}'

Webhook 推送包含两个安全 Header：

X-AgentMail-Signature —— 请求体的 HMAC-SHA256 十六进制摘要，使用 Webhook 密钥签名。

X-AgentMail-Timestamp —— 发送时的毫秒级时间戳。

请验证签名并拒绝时间戳超过 5 分钟的请求，以防止重放攻击：

typescript

import { createHmac } from "crypto";
const verifyWebhook = (body: string, signature: string, timestamp: string, secret: string) => {
  if (Date.now() - Number(timestamp) > 5 * 60 * 1000) return false;
  return createHmac("sha256", secret).update(body).digest("hex") === signature;
};

下载附件

bash

curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId} \
  -H "Authorization: Bearer am_..."

返回：{"data": {"url": "https://signed-download-url..."}}。

完整内容

API 参考

| 方法 | 路径 | 描述 | Karma |
|--------|------|-------------|-------|
| POST | /v1/accounts | 创建邮箱账户 | -10 |
| GET | /v1/accounts | 列出所有账户 | |
| GET | /v1/accounts/:id | 获取账户详情 | |
| DELETE | /v1/accounts/:id | 删除账户 | +10 |
| POST | /v1/accounts/:id/messages | 发送邮件 | -1 |
| GET | /v1/accounts/:id/messages | 列出邮件 | |
| GET | /v1/accounts/:id/messages/:msgId | 获取完整邮件内容 | |
| GET | /v1/accounts/:id/messages/:msgId/attachments/:attId | 获取附件 URL | |
| POST | /v1/accounts/:id/webhooks | 注册 Webhook | |
| GET | /v1/accounts/:id/webhooks | 列出 Webhooks | |
| DELETE | /v1/accounts/:id/webhooks/:whId | 删除 Webhook | |
| GET | /v1/karma | 获取余额及事件 | |

Karma 系统

每项操作都有相应的 Karma 消耗或奖励：

| 事件 | Karma | 原因 |
|---|---|---|
| money_paid | +100 | 购买额度 |
| email_received | +2 | 收到来自信任域名的回复 |
| account_deleted | +10 | 删除地址时退还 Karma |
| email_sent | -1 | 发送邮件消耗 Karma |
| account_created | -10 | 创建地址消耗 Karma |

重要规则：

仅针对来自信任提供商（Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, Hey 等）的入站邮件授予 Karma。来自未知或临时域名的邮件不产生 Karma。

在 Agent 回复之前，每个发送者仅能产生一次 Karma。如果发送者 X 在你未回复的情况下发送了 5 封邮件，只有第一封能获得 Karma。当你回复 X 后，X 的下一封邮件将再次获得 Karma。

删除账户将退还创建时消耗的 10 Karma。

当 Karma 达到 0 时，发送邮件和创建账户将返回 HTTP 402。在执行消耗 Karma 的操作前，请务必检查余额。

TypeScript SDK

typescript

import { createClient } from "@agentmail/sdk";
const mail = createClient({ apiKey: "am_..." });
// 创建账户
const account = await mail.accounts.create({
  address: "[email protected]",
});
// 发送邮件
await mail.messages.send(account.id, {
  to: ["[email protected]"],
  subject: "Hello",
  text: "Sent by an AI agent.",
});
// 读取收件箱
const messages = await mail.messages.list(account.id);
const detail = await mail.messages.get(account.id, messages[0].id);
// 附件
const att = await mail.attachments.getUrl(accountId, messageId, attachmentId);
// att.url 是一个带签名的下载 URL
// Webhooks
await mail.webhooks.create(account.id, {
  url: "https://my-agent.example.com/inbox",
});
// Karma
const karma = await mail.karma.getBalance();
console.log(karma.balance);

错误处理

typescript

import { AgentMailError } from "@agentmail/sdk";
try {
  await mail.messages.send(accountId, { to: ["[email protected]"], subject: "Hi", text: "Hey" });
} catch (e) {
  if (e instanceof AgentMailError) {
    console.log(e.status);   // 402, 404, 401 等
    console.log(e.code);     // "INSUFFICIENT_KARMA", "NOT_FOUND" 等
    console.log(e.message);
  }
}

常见模式

注册服务并读取验证邮件

typescript

const account = await mail.accounts.create({
  address: "[email protected]",
});
// 使用该地址进行注册（通过浏览器自动化、API 等）
// 轮询验证邮件
for (let i = 0; i < 30; i++) {
  const messages = await mail.messages.list(account.id);
  const verification = messages.find(m =>
    m.subject.toLowerCase().includes("verify") ||
    m.subject.toLowerCase().includes("co

nfirm")
);
if (verification) {
const detail = await mail.messages.get(account.id, verification.id);
// 从 detail.bodyText 或 detail.bodyHtml 中解析验证链接/代码
break;
}
await new Promise(r => setTimeout(r, 2000));
}

code

### 发送邮件并等待回复

typescript
const sent = await mail.messages.send(account.id, {
to: ["[email protected]"],
subject: "关于订单 #12345 的问题",
text: "能帮我检查一下状态吗？",
});

for (let i = 0; i < 60; i++) {
const messages = await mail.messages.list(account.id);
const reply = messages.find(m =>
m.direction === "inbound" && m.timestamp > sent.timestamp
);
if (reply) {
const detail = await mail.messages.get(account.id, reply.id);
// 处理回复
break;
}
await new Promise(r => setTimeout(r, 5000));
}

code

## 类型定义

typescript
type Account = { id: string; address: string; displayName: string | null; createdAt: number };
type Message = { id: string; from: string; to: string[]; subject: string; direction: "inbound" | "outbound"; status: string; timestamp: number };
type MessageDetail = Message & { cc: string[] | null; bcc: string[] | null; bodyText: string | null; bodyHtml: string | null; inReplyTo: string | null; references: string | null; attachments: AttachmentMeta[] };
type AttachmentMeta = { id: string; filename: string; contentType: string; size: number };
type KarmaBalance = { balance: number; events: KarmaEvent[] };
type KarmaEvent = { id: string; type: string; amount: number; timestamp: number; metadata?: Record<string, unknown> };
```

限制条件

仅在任务明确符合上述范围时使用此技能。

不要将输出结果视为环境特定验证、测试或专家评审的替代方案。

如果缺少必要的输入、权限、安全边界或成功标准，请停止操作并请求澄清。

智能邮件代理

AgentMail — AI Agent 专用邮箱

使用场景

快速上手

创建电子邮件账户 (-10 karma)

发送邮件 (-1 karma)

读取收件箱

获取完整消息（包含正文和附件）

查询 Karma 余额

注册 Webhook（实时入站通知）

下载附件

完整内容

Karma 系统

TypeScript SDK

错误处理

常见模式

注册服务并读取验证邮件

限制条件

扫码进交流群