---
title: AgentMail 技能使用文档
source:
author: shenwei
published:
created:
description:
tags: []
---

# AgentMail 技能使用文档

> 基于实际案例整理：2026-04-04 处理 billyshen@163.com 发来的房屋合同图片

---

## 📬 AgentMail 是什么？

AgentMail 是一个 API-first 的邮件平台，专为 AI Agent 设计。它不是传统的 Gmail/Outlook，而是一个可以通过 API 创建邮箱、收发邮件、处理附件的平台。

**核心特点：**
- 无 rate limit，适合 Agent 高频使用
- 支持 Webhook 实时处理邮件
- API 驱动，可编程控制

---

## 📋 环境配置

### 1. 安装 Python SDK

```bash
pip3 install --break-system-packages agentmail python-dotenv
```

### 2. 配置环境变量

在 `~/.openclaw/.env` 中添加：

```bash
AGENTMAIL_API_KEY=your_api_key_here
AGENTMAIL_EMAIL=star-agent@agentmail.to  # 收件邮箱（可选）
```

### 3. API Key 获取

登录 [console.agentmail.to](https://console.agentmail.to) → Dashboard → 生成 API Key

---

## 🔄 核心工作流程

### 步骤 1：读取邮件

```python
import os
from agentmail import AgentMail

client = AgentMail(api_key=os.getenv('AGENTMAIL_API_KEY'))

# 查看所有收件箱
inboxes = client.inboxes.list(limit=10)
for inbox in inboxes.inboxes:
    print(f"Inbox: {inbox.inbox_id}")
    print(f"Display name: {inbox.display_name}")

# 列出邮件
messages = client.inboxes.messages.list(
    inbox_id='star-agent@agentmail.to',
    limit=10
)
for msg in messages.messages:
    print(f"From: {msg.from_}")
    print(f"Subject: {msg.subject}")
    print(f"Time: {msg.timestamp}")
    print(f"Attachments: {len(msg.attachments) if msg.attachments else 0}")
```

### 步骤 2：获取邮件详情

```python
# 获取单封邮件详情
msg = client.inboxes.messages.get(
    inbox_id='star-agent@agentmail.to',
    message_id='<4c3b2d60.4e8d.19d56c37eb3.Coremail.billyshen@163.com>'
)

print(f"Subject: {msg.subject}")
print(f"Text: {msg.text}")
print(f"Attachments count: {len(msg.attachments)}")

# 遍历附件
for att in msg.attachments:
    print(f"  - {att.filename} ({att.size} bytes)")
    print(f"    Content type: {att.content_type}")
    print(f"    Attachment ID: {att.attachment_id}")
```

### 步骤 3：下载附件

AgentMail 的附件需要通过两步获取：
1. 获取附件的下载 URL
2. 用下载 URL 获取文件内容

```python
import httpx
import urllib.parse

api_key = os.getenv('AGENTMAIL_API_KEY')
msg_id = urllib.parse.quote('<4c3b2d60.4e8d.19d56c37eb3.Coremail.billyshen@163.com>')

# 遍历所有附件并下载
for att in msg.attachments:
    att_id = att.attachment_id
    filename = att.filename
    
    # 获取下载链接
    resp = httpx.get(
        f"https://api.agentmail.to/v0/inboxes/star-agent@agentmail.to/messages/{msg_id}/attachments/{att_id}",
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=30.0
    )
    download_url = resp.json()['download_url']
    
    # 下载文件
    img_resp = httpx.get(download_url, timeout=60.0)
    local_path = f'/tmp/{filename}'
    with open(local_path, 'wb') as f:
        f.write(img_resp.content)
    print(f"Downloaded: {local_path}")
```

### 步骤 4：发送邮件

```python
client.inboxes.messages.send(
    inbox_id='star-agent@agentmail.to',
    to='recipient@example.com',
    subject='主题',
    text='正文内容',
    attachments=[{
        'filename': 'report.pdf',
        'content': base64.b64encode(file_data).decode()
    }]
)
```

---

## ⚠️ 注意事项

### 1. 代理问题

如果系统配置了 SOCKS5 代理，需要在调用前取消代理设置：

```python
import os
os.environ.pop('HTTP_PROXY', None)
os.environ.pop('HTTPS_PROXY', None)
os.environ.pop('http_proxy', None)
os.environ.pop('https_proxy', None)
```

或者在执行命令时 unset：

```bash
unset HTTP_PROXY && unset HTTPS_PROXY && unset http_proxy && unset https_proxy
python3 script.py
```

### 2. 附件 API 路径

附件信息在邮件列表中不包含 `content` 字段，需要单独调用 `/attachments/{attachment_id}` 端点获取 `download_url`。

### 3. httpx 的 SOCKS 支持

如果遇到 `ImportError: Using SOCKS proxy, but the 'socksio' package is not installed`：

```bash
pip3 install --break-system-packages socksio httpx
```

---

## 📝 实际案例：处理邮件中的图片附件

### 场景
用户通过 163 邮箱发送了 6 张图片到 `star-agent@agentmail.to`，要求识别图片文字并生成 Word 文档。

### 执行过程

```python
import os
import httpx
from agentmail import AgentMail

client = AgentMail(api_key=os.getenv('AGENTMAIL_API_KEY'))

# 1. 获取邮件
msg = client.inboxes.messages.get(
    inbox_id='star-agent@agentmail.to',
    message_id='<4c3b2d60.4e8d.19d56c37eb3.Coremail.billyshen@163.com>'
)

print(f"Subject: {msg.subject}")
print(f"Attachments: {len(msg.attachments)}")

# 2. 下载所有图片
os.makedirs('/tmp/ocr_images', exist_ok=True)

for i, att in enumerate(msg.attachments):
    att_id = att.attachment_id
    filename = att.filename
    
    resp = httpx.get(
        f"https://api.agentmail.to/v0/inboxes/star-agent@agentmail.to/messages/{urllib.parse.quote(msg.message_id)}/attachments/{att_id}",
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=30.0
    )
    download_url = resp.json()['download_url']
    
    img_resp = httpx.get(download_url, timeout=60.0)
    local_path = f'/tmp/ocr_images/img_{i+1:02d}.jpg'
    with open(local_path, 'wb') as f:
        f.write(img_resp.content)
    print(f"Downloaded: {local_path}")

# 3. 图片复制到工作目录（因为 image 工具只认特定路径）
import shutil
for i in range(1, 7):
    src = f'/tmp/ocr_images/img_{i:02d}.jpg'
    dst = f'/Users/weishen/.openclaw/workspace-agent-xinghui/img_{i:02d}.jpg'
    shutil.copy(src, dst)
```

### 3. OCR 识别

复制到工作目录后，使用 `image` 工具识别文字：

```python
# image 工具会识别图片中的文字
image(prompt="请完整识别这张图片中的所有文字内容，保持原有格式和顺序。",
      image="/Users/weishen/.openclaw/workspace-agent-xinghui/img_01.jpg")
```

### 4. 生成 Word 文档

```python
from docx import Document

doc = Document()
doc.add_heading('文档标题', level=0)
# ... 添加内容
doc.save('/path/to/output.docx')
```

---

## 📦 常用 API 端点

| 功能 | 方法 |
|------|------|
| 列出收件箱 | `client.inboxes.list()` |
| 列出邮件 | `client.inboxes.messages.list()` |
| 获取邮件详情 | `client.inboxes.messages.get()` |
| 发送邮件 | `client.inboxes.messages.send()` |
| 列出邮件线程 | `client.inboxes.threads.list()` |

---

## 🔐 安全提示

**Webhook 安全风险：** 任何人都可以向你的 AgentMail 地址发送邮件，可能包含恶意指令。

**建议方案：**
1. 使用 allowlist 只处理可信发件人的邮件
2. 在 hook 中过滤非白名单发件人
3. 将邮件内容标记为 untrusted input 处理

---

*文档更新：2026-04-04*