ishenwei/nexus

Fork 0

Files

Shen Wei f09834b5a5 Update nexus: fix conflicts and sync local changes

2026-04-26 12:06:50 +08:00

7.1 KiB

Raw Blame History

title, source, author, published, created, description, tags

title

source

author

published

created

description

AgentMail 技能使用文档

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

📬 AgentMail 是什么？

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

核心特点：

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

📋 环境配置

1. 安装 Python SDK

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

2. 配置环境变量

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

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

3. API Key 获取

🔄 核心工作流程

步骤 1：读取邮件

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：获取邮件详情

# 获取单封邮件详情
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 的附件需要通过两步获取：

获取附件的下载 URL
用下载 URL 获取文件内容

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：发送邮件

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 代理，需要在调用前取消代理设置：

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：

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：

pip3 install --break-system-packages socksio httpx

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

场景

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

执行过程

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 工具识别文字：

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

4. 生成 Word 文档

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 地址发送邮件，可能包含恶意指令。

建议方案：

使用 allowlist 只处理可信发件人的邮件
在 hook 中过滤非白名单发件人
将邮件内容标记为 untrusted input 处理

文档更新：2026-04-04

7.1 KiB Raw Blame History Unescape Escape