AgenticEmail:AI 代理的電子郵件服務
AgenticEmail 賦予代理一個真實且可收發信的電子郵件收件匣。與僅能外寄的發送 API 不同,每個收件匣既可傳送也可接收郵件:入站信件會以解析後的 JSON 格式,透過 webhook 或 WebSocket 串流送達。當代理需要以電子郵件地址被聯繫,而不僅僅是能夠發信時,就該選用它。
常見觸發情境:代理必須註冊第三方服務、接收驗證碼或一次性密碼(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 token 連接
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 "由代理發送。"
agenticemail messages list "$INBOX" --limit 5
agenticemail messages reply "$INBOX" <msgId> --text "正在處理。"
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: "由代理發送。",
});
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: "謝謝。" });
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)
基礎網址為 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 的要求。
- 若遺失私鑰,舊的加密郵件將無法復原。這是伺服器從未持有私鑰所必須付出的代價。