星辉: 新增AgentMail技能使用指南（基于实际案例整理）
This commit is contained in:
272
openclaw/knowledgebase/AgentMail-技能使用指南.md
Normal file
272
openclaw/knowledgebase/AgentMail-技能使用指南.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user