277 lines
6.8 KiB
Markdown
277 lines
6.8 KiB
Markdown
---
|
||
title: AgentMail 技能使用文档
|
||
author: shenwei
|
||
---
|
||
# 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*
|