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": "[email protected]"}'
回應:{"data": {"id": "...", "address": "[email protected]", "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": ["[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 編碼)。
讀取收件匣
# 列出訊息
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
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-- 以 Webhook 密鑰簽署的請求主體 HMAC-SHA256 十六進位摘要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 |
重要規則:
- 僅有來自受信任提供者(Gmail、Outlook、Yahoo、iCloud、ProtonMail、Fastmail、Hey 等)的入站電子郵件才能獲得 Karma。來自未知/一次性網域的郵件不會獲得 Karma。
- 在代理回覆之前,您每個寄件者只能獲得一次 Karma。如果寄件者 X 在沒有回覆的情況下給您發了 5 封郵件,只有第一封能獲得 Karma。回覆 X 後,來自 X 的下一封郵件才能再次獲得 Karma。
- 刪除帳戶會退還建立時花費的 10 點 Karma。
當 Karma 達到 0 時,發送郵件和建立帳戶的操作會返回 HTTP 402。在執行消耗 Karma 的操作前,請務必檢查餘額。
TypeScript SDK
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
// Webhook
await mail.webhooks.create(account.id, {
url: "https://my-agent.example.com/inbox",
});
// Karma
const karma = await mail.karma.getBalance();
console.log(karma.balance);
錯誤處理
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);
}
}
常見模式
註冊服務並讀取驗證郵件
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("confirm")
);
if (verification) {
const detail = await mail.messages.get(account.id, verification.id);
// 從 detail.bodyText 或 detail.bodyHtml 解析驗證連結/驗證碼
break;
}
await new Promise(r => setTimeout(r, 2000));
}
發送郵件並等待回覆
const sent = await mail.messages.send(account.id, {
to: ["[email protected]"],
subject: "Question about order #12345",
text: "Can you check the status?",
});
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));
}
型別
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> };
限制
- 僅在任務明確符合上述描述範圍時使用此技能。
- 請勿將輸出視為環境特定驗證、測試或專家審查的替代品。
- 如果缺少必要的輸入、權限、安全邊界或成功條件,請停止並要求澄清。