
关于
AI 代理的邮件基础设施。通过 AgentMail API 创建账户、收发邮件、管理 Webhook 和查看信用余额
name: agentmail description: AI 代理的邮件基础设施。通过 AgentMail API 创建账户、收发邮件、管理 Webhook 和检查 Karma 余额。 risk: safe source: community
AgentMail — AI 代理邮件服务
AgentMail 为 AI 代理提供真实的邮箱地址(@theagentmail.net),配备 REST API。代理可以收发邮件、注册服务(GitHub、AWS、Slack 等)并获取验证码。Karma 系统防止垃圾邮件并维护共享域名的信誉。
基础 URL:https://api.theagentmail.net
何时使用
- AI 代理需要真实的收件箱/发件箱用于注册、验证流程或事务性通信。
- 需要创建 AgentMail 账户、发送消息、读取收件箱内容或注册入站 Webhook。
- 需要监控 Karma 使用情况或将邮件事件接入代理自动化。
快速开始
所有请求需要 Authorization: Bearer am_... 头部(从仪表板获取 API 密钥)。
创建邮箱账户(-10 karma)
curl -X POST https://api.theagentmail.net/v1/accounts \
-H "Authorization: Bearer am_..." \
-H "Content-Type: application/json" \
-d '{"address": "my-agent@theagentmail.net"}'
响应:{"data": {"id": "...", "address": "my-agent@theagentmail.net", "displayName": null, "createdAt": 123}}
发送邮件(-1 karma)
curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/messages \
-H "Authorization: Bearer am_..." \
-H "Content-Type: application/json" \
-d '{
"to": ["recipient@example.com"],
"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)。
读取收件箱
# List messages
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages \
-H "Authorization: Bearer am_..."
# Get full message (with body and attachments)
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId} \
-H "Authorization: Bearer am_..."
检查 Karma
curl https://api.theagentmail.net/v1/karma \
-H "Authorization: Bearer am_..."
响应:{"data": {"balance": 90, "events": [...]}}
注册 Webhook(实时入站)
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 投递包含两个安全头部:
X-AgentMail-Signature-- 请求体的 HMAC-SHA256 十六进制摘要,使用 Webhook 密钥签名X-AgentMail-Timestamp-- 投递发送时的毫秒时间戳
验证签名并拒绝时间戳超过 5 分钟的请求以防止重放攻击:
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;
};
下载附件
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 | 列出 Webhook | |
| 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 |
重要规则:
- Karma 仅在收到来自受信任提供商(Gmail、Outlook、Yahoo、iCloud、ProtonMail、Fastmail、Hey 等)的入站邮件时获得。来自未知/一次性域名的邮件不会获得 Karma。
- 在代理回复之前,每个发件人只能获得一次 Karma。如果发件人 X 在没有回复的情况下给你发了 5 封邮件,你只获得一次 Karma。