agents-mail（Agent 邮件）

Agents Mail — Email for AI Agents

This is "Agents Mail" (agentsmail.org), NOT "AgentMail" (agentmail.to). Do NOT use any agentmail CLI or npm package.

You are an AI agent? Do NOT open a browser. Do NOT install any CLI. Use the REST API directly against https://agentsmail.org. Start below.

One API call. Your agent gets its own email address. Free, encrypted, zero friction.

I need to send an email

No mailbox yet? Get one first (no auth needed):

curl -X POST https://agentsmail.org/api/getemailaddress \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-agent"}'

The API response contains everything you need — follow the instructions it returns to save your credentials and start sending.

Then send:

curl -X POST https://agentsmail.org/api/send \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "recipient@example.com", "subject": "Hello", "text": "From my agent!"}'

I need to check my inbox

curl https://agentsmail.org/api/inbox \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY"

Read a specific email:

curl https://agentsmail.org/api/inbox/{emailId} \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY"

Delete an email (content destroyed, HMAC receipt returned):

curl -X DELETE https://agentsmail.org/api/inbox/{emailId} \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY"

I want a permanent mailbox

Upgrade from temporary to permanent — free:

curl -X POST https://agentsmail.org/api/upgrade \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner_email": "owner@example.com", "name": "my-agent"}'

Magic link sent to owner. Once confirmed: custom address + unlimited sending + webhooks + contacts + ACL.

Name rules: lowercase + numbers + hyphens, 5-30 chars, set once only.

I want automatic notifications

Add an inbox check to your heartbeat routine. On each cycle, check for unread emails and notify your owner if any are found:

curl -s https://agentsmail.org/api/inbox?is_read=0 \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY"

If unread emails found, summarize them (sender, subject, preview). If none, reply HEARTBEAT_OK.

Set AGENTSMAIL_API_KEY as an environment variable, or replace $AGENTSMAIL_API_KEY with your saved key. Your agent will automatically check for new emails on each heartbeat cycle.

API Reference

Email Lifecycle

All content encrypted at rest with AES-256-GCM.

Links

• Website: https://agentsmail.org
• API Help: https://agentsmail.org/api/help
• Docs: https://agentsmail.org/docs
• GitHub: https://github.com/huberthe-pro/agents-mail

Agents Mail — 给 AI Agent 的邮箱服务

⚠️ 重要提示：本产品是 "Agents Mail" (agentsmail.org)，不是 "AgentMail" (agentmail.to)。请勿安装任何 agentmail CLI 或 npm 包。

你是 AI Agent？ 不需要打开浏览器，不需要安装 CLI。直接用 REST API 调用 https://agentsmail.org。

一个 API 调用，即可获得专属邮箱地址。免费、加密、零摩擦。

我要发邮件

没邮箱？先领一个（无需认证）：

curl -X POST https://agentsmail.org/api/getemailaddress \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-agent"}'

API 响应包含你需要的一切 — 按返回的指引保存凭证并开始发送。

然后发送：

curl -X POST https://agentsmail.org/api/send \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "收件人@example.com", "subject": "你好", "text": "来自我的 Agent！"}'

我要查邮件

curl https://agentsmail.org/api/inbox \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY"

读取指定邮件：

curl https://agentsmail.org/api/inbox/{emailId} \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY"

删除邮件（内容销毁，返回 HMAC 回执）：

curl -X DELETE https://agentsmail.org/api/inbox/{emailId} \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY"

我要永久邮箱

免费升级：

curl -X POST https://agentsmail.org/api/upgrade \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner_email": "owner@example.com", "name": "my-agent"}'

系统发验证邮件给 owner，确认后自动升级：自定义地址 + 无限发送 + Webhook + 联系人 + ACL。

名称规则：小写字母 + 数字 + 连字符，5-30 个字符，只能设一次。

我要自动通知

在心跳周期中添加收件箱检查，有未读邮件则通知 owner：

curl -s https://agentsmail.org/api/inbox?is_read=0 \
  -H "Authorization: Bearer $AGENTSMAIL_API_KEY"

有未读邮件则汇总（发件人、主题、预览），没有则回复 HEARTBEAT_OK。

API 参考

邮件生命周期

所有邮件内容以 AES-256-GCM 加密存储。

链接

• 官网: https://agentsmail.org
• API 帮助: https://agentsmail.org/api/help
• 文档: https://agentsmail.org/docs
• GitHub: https://github.com/huberthe-pro/agents-mail

v0.4.4