Skill: agents-mail/agents-mail (version 0.4.4)

--- name: Agents Mail description: Free email for AI agents. No sign-up needed. One call to get a mailbox and send. version: 0.4.4 emoji: "📧" homepage: https://agentsmail.org source: https://github.com/huberthe-pro/agents-mail license: MIT --- # 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): ```bash 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: ```bash curl -X POST https://agentsmail.org/api/send \ -H "Authorization: Bearer $AGENTSMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"to": "[REDACTED_SECRET]", "subject": "Hello", "text": "From my agent!"}' ``` ## I need to check my inbox ```bash curl https://agentsmail.org/api/inbox \ -H "Authorization: Bearer $AGENTSMAIL_API_KEY" ``` Read a specific email: ```bash curl https://agentsmail.org/api/inbox/{emailId} \ -H "Authorization: Bearer $AGENTSMAIL_API_KEY" ``` Delete an email (content destroyed, HMAC receipt returned): ```bash 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: ```bash curl -X POST https://agentsmail.org/api/upgrade \ -H "Authorization: Bearer $AGENTSMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"owner_email": "[REDACTED_SECRET]", "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: ```bash 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 | Method | Path | Auth | Description | |--------|------|------|-------------| | GET | /api/help | None | API directory | | POST | /api/getemailaddress | None | Get a mailbox | | POST | /api/send | API Key | Send email | | GET | /api/inbox | API Key | Check inbox | | GET | /api/inbox/:id | API Key | Read email | | DELETE | /api/inbox/:id | API Key | Delete email | | GET | /api/sent | API Key | Sent emails | | DELETE | /api/sent/:id | API Key | Delete sent | | POST | /api/upgrade | API Key | Permanent mailbox | | POST | /api/webhooks | Tier 1+ | Add webhook | | GET | /api/contacts | Tier 1+ | Manage contacts | | POST | /api/acl | Tier 1+ | Sender rules | ## Email Lifecycle | Status | Tier 0 | Tier 1+ | |--------|--------|---------| | unread | Kept until account recycled (30d) | Kept permanently | | read | Kept until account recycled | Kept permanently | | sent | Kept until account recycled | Kept permanently | | deleted | Content destroyed, envelope preserved, HMAC receipt | Same | 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 调用，即可获得专属邮箱地址。免费、加密、零摩擦。 ## 我要发邮件 没邮箱？先领一个（无需认证）： ```bash curl -X POST https://agentsmail.org/api/getemailaddress \ -H "Content-Type: application/json" \ -d '{"agent_name": "my-agent"}' ``` API 响应包含你需要的一切 — 按返回的指引保存凭证并开始发送。 然后发送： ```bash 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！"}' ``` ## 我要查邮件 ```bash curl https://agentsmail.org/api/inbox \ -H "Authorization: Bearer $AGENTSMAIL_API_KEY" ``` 读取指定邮件： ```bash curl https://agentsmail.org/api/inbox/{emailId} \ -H "Authorization: Bearer $AGENTSMAIL_API_KEY" ``` 删除邮件（内容销毁，返回 HMAC 回执）： ```bash curl -X DELETE https://agentsmail.org/api/inbox/{emailId} \ -H "Authorization: Bearer $AGENTSMAIL_API_KEY" ``` ## 我要永久邮箱 免费升级： ```bash curl -X POST https://agentsmail.org/api/upgrade \ -H "Authorization: Bearer $AGENTSMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"owner_email": "[REDACTED_SECRET]", "name": "my-agent"}' ``` 系统发验证邮件给 owner，确认后自动升级：自定义地址 + 无限发送 + Webhook + 联系人 + ACL。 名称规则：小写字母 + 数字 + 连字符，5-30 个字符，只能设一次。 ## 我要自动通知 在心跳周期中添加收件箱检查，有未读邮件则通知 owner： ```bash curl -s https://agentsmail.org/api/inbox?is_read=0 \ -H "Authorization: Bearer $AGENTSMAIL_API_KEY" ``` 有未读邮件则汇总（发件人、主题、预览），没有则回复 HEARTBEAT_OK。 ## API 参考 | 方法 | 路径 | 认证 | 说明 | |------|------|------|------| | GET | /api/help | 无 | API 目录 | | POST | /api/getemailaddress | 无 | 领邮箱 | | POST | /api/send | API Key | 发邮件 | | GET | /api/inbox | API Key | 查收件箱 | | GET | /api/inbox/:id | API Key | 读邮件 | | DELETE | /api/inbox/:id | API Key | 删除邮件 | | GET | /api/sent | API Key | 已发邮件 | | DELETE | /api/sent/:id | API Key | 删除已发 | | POST | /api/upgrade | API Key | 永久邮箱 | | POST | /api/webhooks | Tier 1+ | Webhook | | GET | /api/contacts | Tier 1+ | 联系人 | | POST | /api/acl | Tier 1+ | 发件人规则 | ## 邮件生命周期 | 状态 | Tier 0 | Tier 1+ | |------|--------|---------| | 未读 | 保留到账号回收（30天无活动） | 永久保留 | | 已读 | 保留到账号回收 | 永久保留 | | 已发 | 保留到账号回收 | 永久保留 | | 已删除 | 内容立即销毁，信封保留，HMAC 回执 | 同左 | 所有邮件内容以 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

path: references/EXAMPLES.md
content: # Agents Mail — Common Patterns (v0.4)

## Pattern 1: Get Mailbox and Send (Zero Setup)

```python
import requests, os

# One call — no sign-up, no API key needed
agent = requests.post("https://agentsmail.org/api/getemailaddress",
    json={"agent_name": "inbox-watcher"}).json()

# Store securely as environment variable (NOT in plaintext files)
# os.environ["AGENTSMAIL_API_KEY"] = agent["api_key"]
[REDACTED_SECRET]"api_key"]

print(f"Email: {agent['email']}")

# Send immediately — 10 free sends at Tier 0
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
result = requests.post("https://agentsmail.org/api/send",
    headers=headers,
    json={
        "to": "[REDACTED_SECRET]",
        "subject": "Hello from my agent",
        "text": "I just got my own email address!"
    }).json()

print(f"Sent! Remaining: {result['trial_sends']['remaining']}")
```

## Pattern 2: Check Inbox

```python
import requests

[REDACTED_SECRET]"AGENTSMAIL_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}

# Check for unread emails
emails = requests.get("https://agentsmail.org/api/inbox?is_read=0",
    headers=headers).json()

for email in emails.get("emails", []):
    print(f"From: {email['from']}, Subject: {email['subject']}")
```

## Pattern 3: Auto-Responder

Poll inbox and reply to new messages:

```python
import requests, time, os

API = "https://agentsmail.org/api"
[REDACTED_SECRET]"AGENTSMAIL_API_KEY")
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

while True:
    emails = requests.get(f"{API}/inbox?is_read=0", headers=headers).json()

    for email in emails.get("emails", []):
        # Read the full email (auto-marks as read)
        detail = requests.get(f"{API}/inbox/{email['email_id']}", headers=headers).json()

        # Reply
        requests.post(f"{API}/send", headers=headers, json={
            "to": detail["from"],
            "subject": f"Re: {detail['subject']}",
            "text": f"Got your message. Processing now."
        })

    time.sleep(30)
```

## Pattern 4: Upgrade to Permanent Mailbox

```python
import requests, os

[REDACTED_SECRET]"AGENTSMAIL_API_KEY")
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

# Upgrade — owner gets magic link, click to confirm
result = requests.post("https://agentsmail.org/api/upgrade",
    headers=headers,
    json={
        "owner_email": "[REDACTED_SECRET]",
        "name": "my-agent"
    }).json()

print(f"Future email: {result['future_email']}")
# → [REDACTED_SECRET] (after owner confirms)
```

## Pattern 5: Webhook-Driven Pipeline (Tier 1+)

```python
import requests, os

[REDACTED_SECRET]"AGENTSMAIL_API_KEY")
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

# Register webhook (must be public HTTPS)
webhook = requests.post("https://agentsmail.org/api/webhooks",
    headers=headers,
    json={
        "url": "https://your-server.com/incoming-email",
        "events": ["email.received"]
    }).json()

print(f"Webhook [REDACTED_SECRET]'secret']}")  # For HMAC verification
```

Handle incoming webhooks:

```python
from flask import Flask, request
import hmac, hashlib

app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get("AGENTSMAIL_WEBHOOK_SECRET")

@app.route("/incoming-email", methods=["POST"])
def handle():
    sig = request.headers.get("X-Webhook-Signature", "")
    expected = hmac.new(WEBHOOK_SECRET.encode(), request.data, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, expected):
        return "Bad signature", 401

    email = request.json
    print(f"New email from {email['from']}: {email['subject']}")
    return "OK"
```

## Pattern 6: HEARTBEAT.md (Recommended for OpenClaw / Local Agents)

For agents without a public server, add inbox checking to your HEARTBEAT.md:

```markdown
## Check AgentsMail Inbox

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

If there are unread emails, summarize them (sender, subject, preview).
If no unread emails, reply HEARTBEAT_OK.
```

This automatically checks your inbox on each heartbeat cycle (typically every 30 minutes) and notifies your owner when new emails arrive.

## Pattern 7: Access Control (Tier 1+)

```python
import requests, os

[REDACTED_SECRET]"AGENTSMAIL_API_KEY")
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

# Whitelist trusted senders
requests.post("https://agentsmail.org/api/acl", headers=headers,
    json={"email": "[REDACTED_SECRET]", "type": "whitelist"})

# Blacklist spam
requests.post("https://agentsmail.org/api/acl", headers=headers,
    json={"email": "[REDACTED_SECRET]", "type": "blacklist"})
```


path: references/API.md
content: # Agents Mail API Reference (v0.4.4)

**Base URL:** `https://agentsmail.org`
**Homepage:** https://agentsmail.org
**Source:** https://github.com/huberthe-pro/agents-mail (MIT)

All requests and responses use JSON. Set `Content-Type: application/json` on every request that includes a body.

## Authentication

Use the API key returned from `POST /api/getemailaddress`:

```
Authorization: Bearer am_sk_<64-hex-characters>
```

`POST /api/getemailaddress` and `GET /api/help` require no authentication. All other endpoints require an API key. The key identifies your mailbox — no agent ID needed in URLs.

**Security:** Store your API key as an environment variable (`AGENTSMAIL_API_KEY`), not in plaintext files. The API key is shown only once at registration.

## Endpoints

### GET /api/help — API Directory

```bash
curl https://agentsmail.org/api/help
```

Returns all available endpoints, email lifecycle rules, and rate limits.

---

### POST /api/getemailaddress — Get a Free Mailbox

**No authentication required.**

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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| agent_name | string | Yes | Agent display name |

**Response (201):**

```json
{
  "email": "[REDACTED_SECRET]",
  "agent_name": "my-agent",
  "api_key": "am_sk_abc123...",
  "tier_level": 0,
  "trial_sends": { "limit": 10, "remaining": 10 },
  "help": "https://agentsmail.org/api/help"
}
```

> **IMPORTANT:** `api_key` is shown only once. Store it as an environment variable immediately.

---

### POST /api/send — Send Email

Tier 0: 10 trial sends. Tier 1+: unlimited.

```bash
curl -X POST https://agentsmail.org/api/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "to": "[REDACTED_SECRET]",
    "subject": "Hello",
    "text": "Message body"
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| to | string | Yes | Recipient email |
| subject | string | Yes | Email subject |
| text | string | Yes | Plain text body |
| html | string | No | HTML body |

**Response (200):**

```json
{
  "status": "sent",
  "tier_level": 0,
  "trial_sends": { "remaining": 9, "limit": 10 },
  "help": "https://agentsmail.org/api/help"
}
```

---

### GET /api/inbox — Check Inbox

```bash
curl https://agentsmail.org/api/inbox \
  -H "Authorization: Bearer {api_key}"
```

| Parameter | Type | Description |
|-----------|------|-------------|
| is_read | 0 or 1 | Filter unread/read |
| from | string | Filter by sender |
| limit | integer | Items per page (default 20, max 100) |
| cursor | string | Pagination cursor |

---

### GET /api/inbox/:emailId — Read Email

First read auto-marks status from `unread` to `read`.

```bash
curl https://agentsmail.org/api/inbox/{emailId} \
  -H "Authorization: Bearer {api_key}"
```

---

### DELETE /api/inbox/:emailId — Delete Email

Content destroyed immediately. Returns HMAC-SHA256 receipt. Envelope preserved for audit.

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

---

### GET /api/sent — View Sent Emails

```bash
curl https://agentsmail.org/api/sent \
  -H "Authorization: Bearer {api_key}"
```

---

### DELETE /api/sent/:emailId — Delete Sent Email

```bash
curl -X DELETE https://agentsmail.org/api/sent/{emailId} \
  -H "Authorization: Bearer {api_key}"
```

---

### POST /api/upgrade — Upgrade to Permanent Mailbox

Get custom [REDACTED_SECRET] + unlimited sending. Name can only be set once.

```bash
curl -X POST https://agentsmail.org/api/upgrade \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{"owner_email": "[REDACTED_SECRET]", "name": "my-agent"}'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| owner_email | string | Yes | Owner email for magic link verification |
| name | string | Yes | Custom name (5-30 chars, lowercase + numbers + hyphens) |

---

### POST /api/webhooks — Add Webhook (Tier 1+)

URL must be public HTTPS. No localhost/private IPs.

```bash
curl -X POST https://agentsmail.org/api/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{"url": "https://your-server.com/webhook", "events": ["email.received"]}'
```

Response includes a `secret` for HMAC-SHA256 signature verification (shown only once).

### GET /api/webhooks — List Webhooks (Tier 1+)

### DELETE /api/webhooks/:webhookId — Remove Webhook (Tier 1+)

---

### GET /api/contacts — List Contacts (Tier 1+)

### POST /api/contacts — Add Contact (Tier 1+)

```bash
curl -X POST https://agentsmail.org/api/contacts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{"email": "[REDACTED_SECRET]", "name": "Friend"}'
```

### DELETE /api/contacts/:email — Remove Contact (Tier 1+)

---

### GET /api/acl — List ACL Rules (Tier 1+)

### POST /api/acl — Add ACL Rule (Tier 1+)

```bash
curl -X POST https://agentsmail.org/api/acl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{"email": "[REDACTED_SECRET]", "type": "blacklist"}'
```

Type: `whitelist` or `blacklist`.

### DELETE /api/acl/:email — Remove ACL Rule (Tier 1+)

---

## Email Lifecycle

| Status | Tier 0 | Tier 1+ |
|--------|--------|---------|
| **unread** | Kept until account recycled (30d inactive) | Kept permanently |
| **read** | Kept until account recycled | Kept permanently |
| **sent** | Kept until account recycled | Kept permanently |
| **deleted** | Content destroyed, envelope kept until recycled | Content destroyed, envelope kept permanently |

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

## Rate Limits

| Action | Limit |
|--------|-------|
| Outbound email | 60/min, 1000/hour per mailbox |
| Registration | 10/hour per IP |

429 responses → use exponential backoff starting at 5 seconds.

## Error Codes

| HTTP | Code | Meaning |
|------|------|---------|
| 400 | VALIDATION_ERROR | Missing or invalid parameters |
| 400 | INVALID_WEBHOOK_URL | Not a public HTTPS URL |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | TRIAL_QUOTA_EXCEEDED | Tier 0 send limit reached |
| 403 | UPGRADE_REQUIRED | Feature requires permanent mailbox |
| 404 | NOT_FOUND | Resource not found |
| 409 | NAME_TAKEN | Custom name already in use |
| 409 | ALREADY_UPGRADED | Already a permanent mailbox |
| 409 | ALREADY_DELETED | Email already deleted |
| 429 | RATE_LIMITED | Too many requests |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)