---

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。