back
loading skill details...
职业邮箱收发与数据处理一体化工具。IMAP/SMTP protocol for 12+ providers (Gmail/Outlook/QQ/163/Yahoo/iCloud etc). Send/receive/search/schedule emails, HTML templates, attachmen...
---
name: emailbox
description: 职业邮箱收发与数据处理一体化工具。IMAP/SMTP protocol for 12+ providers (Gmail/Outlook/QQ/163/Yahoo/iCloud etc). Send/receive/search/schedule emails, HTML templates, attachments, forwarding, data integration. 邮件收发、搜索、定时发送、附件、HTML模板、转发、文档数据联动。
version: 1.2.0
license: MIT-0
metadata: {"openclaw": {"emoji": "📬", "requires": {"bins": ["python3"], "env": ["EMAIL_ADDRESS", "EMAIL_AUTH"]}, "primaryEnv": "EMAIL_AUTH"}}
---
# Emailbox - Professional Email Client & Data Integration
IMAP/SMTP-based email toolkit supporting 12+ providers. Send, receive, search, forward, schedule emails with HTML templates, attachments, and document data integration.
> ⚠️ **数据外发提醒**：邮件内容（收件人、主题、正文、附件）通过 IMAP/SMTP 协议直接发送至邮件服务商服务器。涉及发票、合同、简历等敏感数据时，请在发送前确认收件人正确。
>
> ⚠️ **凭据安全**：邮箱授权码等同于密码。环境变量可能通过 shell history、进程列表、CI 日志泄露。每次使用完后建议 `unset EMAIL_AUTH`。
## Features
- **Send**: Plain text, HTML, attachments, CC/BCC, reply, forward
- **Receive**: List inbox, read emails, download attachments
- **Search**: By keyword (subject/from/body), date range, sender
- **Forward**: Fetch original email, forward to new recipients
- **Schedule**: Send emails at a future time
- **Templates**: 7 professional HTML email templates
- **Integration**: Excel/OCR/PDF data → format → email
- **Providers**: QQ, 163, 126, Sina, Outlook, Gmail, Yahoo, iCloud, Tencent Exmail, Ali Mail, Huawei, 139
## Trigger
- "Send email to..." / "发邮件给..."
- "Check inbox" / "查看收件箱"
- "Reply to this email" / "回复这封邮件"
- "Forward this email" / "转发这封邮件"
- "Search emails from..." / "搜索...的邮件"
- "Schedule email for..." / "定时发送..."
- "Process data and email..." / "整理数据后发邮件"
- "Attach this file..." / "添加附件..."
---
## Step 0: Setup
### Quick Start (Single Account)
```bash
# Set 2 environment variables and you're ready
export EMAIL_ADDRESS="your@qq.com"
export EMAIL_AUTH="your_authorization_code"
```
> ⚠️ `export` 设置的变量在当前 shell 及所有子进程可见（包括 ps 命令、CI 日志、崩溃报告）。
> 用完建议 `unset EMAIL_AUTH`，或使用 `.env` 文件 + `source` 替代一次性 export。
### Multi-Account Setup
```bash
# QQ Mail
export EMAIL_QQ="your@qq.com"
export EMAIL_QQ_AUTH="qq_auth_code"
# 163 Mail
export EMAIL_163="your@163.com"
export EMAIL_163_AUTH="163_client_password"
# Gmail
export EMAIL_GMAIL="your@gmail.com"
export EMAIL_GMAIL_AUTH="gmail_app_password"
```
### Provider Auth Guide
How to get authorization codes for each provider → `references/providers.md`
> ⚠️ 授权码等同于邮箱密码，拥有它可以收发你的所有邮件。不要分享给他人，不要在公共终端设置。
### Persistent Config
**IMPORTANT: Never store email credentials in plaintext files.** Use your system's secure credential manager or session-only environment variables.
```bash
# Option A: Session-only (recommended for security)
# Set environment variables in your current shell session only.
# Credentials will NOT persist after the session ends.
export EMAIL_ADDRESS="your@qq.com"
export EMAIL_AUTH="your_auth_code"
# Option B: Keychain / secret manager
# macOS: Use `security add-internet-password`
# Linux: Use `secret-tool store` (libsecret)
# Windows: Use Windows Credential Manager
# Option C: Restricted file (if persistent config is required)
# Create a file with restricted permissions that only you can read:
mkdir -p ~/.emailbox && touch ~/.emailbox/credentials
chmod 600 ~/.emailbox/credentials
# Then add your credentials:
# EMAIL_ADDRESS=your@qq.com
# EMAIL_AUTH=your_auth_code
#
# Before running emailbox commands:
# source ~/.emailbox/credentials
```
---
## Step 1: Send Email
### Plain Text
```bash
python3 scripts/send_mail.py \
--to "recipient@example.com" \
--subject "Project Update" \
--body "Hi, here is the project update..." \
--provider qq
```
### Multiple Recipients + CC/BCC
```bash
python3 scripts/send_mail.py \
--to "boss@company.com,team@company.com" \
--cc "hr@company.com" \
--bcc "archive@company.com" \
--subject "Weekly Report" \
--body "Please find the weekly report attached." \
--provider 163
```
### HTML Email (Use Templates)
Choose a template from `references/templates.md`, fill in variables, save as HTML, then:
```bash
python3 scripts/send_mail.py \
--to "client@company.com" \
--subject "Sales Report - 2026W16" \
--body-file "${OPENCLAW_WORKSPACE:-$PWD}/.emailbox_body.txt" \
--html-file "${OPENCLAW_WORKSPACE:-$PWD}/.emailbox_body.html" \
--provider outlook
```
### With Attachments
```bash
python3 scripts/send_mail.py \
--to "finance@company.com" \
--subject "Invoice - FP20260418001" \
--body "Please find the invoice attached." \
--attach "/path/to/invoice.jpg" "/path/to/detail.xlsx" \
--provider qq
```
### High Priority + Read Receipt
```bash
python3 scripts/send_mail.py \
--to "manager@company.com" \
--subject "URGENT: Contract Review" \
--body "Please review the attached contract ASAP." \
--importance high \
--receipt \
--provider outlook
```
### Reply to Email
First get the Message-ID from reading an email (Step 3), then:
```bash
python3 scripts/send_mail.py \
--to "sender@example.com" \
--subject "Re: Original Subject" \
--body "Got it, confirmed." \
--reply-to "<msgid@example.com>" \
--provider qq
```
### Forward Email
First get the original email metadata (Step 4), then:
```bash
python3 scripts/send_mail.py \
--to "colleague@company.com" \
--subject "Fwd: Original Subject" \
--body "Please see the forwarded message below." \
--forward-from "Original Sender <sender@example.com>" \
--forward-date "Mon, 18 Apr 2026 10:30:00 +0800" \
--forward-subject "Original Subject" \
--forward-to "me@company.com" \
--provider qq
```
---
## Step 2: Receive Email
### List Inbox (Recent Emails)
```bash
python3 scripts/receive_mail.py --list
python3 scripts/receive_mail.py --list --count 20
python3 scripts/receive_mail.py --list --provider gmail
python3 scripts/receive_mail.py --list --folder "Sent Items"
```
### Read Email Content
```bash
python3 scripts/receive_mail.py --read 123 --provider qq
```
### Download Attachments
```bash
python3 scripts/receive_mail.py --read 123 --download-attachment 123 \
--save-dir "${OPENCLAW_WORKSPACE:-$PWD}/downloads"
```
---
## Step 3: Search Email
```bash
# Search by keyword (searches subject, from, AND body)
python3 scripts/receive_mail.py --search "contract" --provider qq
# Search by sender
python3 scripts/receive_mail.py --search "" --from-filter "zhangsan@company.com"
# Search by date range
python3 scripts/receive_mail.py --search "report" --since "2026-04-01"
# Combined search
python3 scripts/receive_mail.py --search "invoice" --from-filter "finance@company.com" --since "2026-04-01" --count 5
```
### IMAP Folders
Access folders beyond INBOX:
```bash
python3 scripts/receive_mail.py --list --folder "Sent Items"
python3 scripts/receive_mail.py --list --folder "Drafts"
python3 scripts/receive_mail.py --list --folder "Trash"
```
Common folder names:
- Gmail: `[Gmail]/Sent Mail`, `[Gmail]/Drafts`, `[Gmail]/Spam`
- QQ Mail: `Sent Messages`, `Drafts`, `Deleted Messages`
- 163 Mail: `Sent`, `Drafts`, `Deleted`
- Outlook: `SentItems`, `Drafts`, `Deleted`
---
## Step 4: Forward Email
```bash
# Step 1: Get original email metadata
python3 scripts/receive_mail.py --forward 123 --provider qq
# Output includes FORWARD_META with From/To/CC/Date/Subject/Message-ID
# Step 2: Forward using the metadata
python3 scripts/send_mail.py \
--to "colleague@company.com" \
--subject "Fwd: Original Subject" \
--body "FYI, please see below." \
--forward-from "Original Sender <sender@example.com>" \
--forward-date "Mon, 18 Apr 2026 10:30:00 +0800" \
--forward-subject "Original Subject" \
--forward-to "me@company.com" \
--provider qq
```
---
## Step 5: Document Data Integration
Combine other Skills' output with email sending.
Detailed workflows → `references/integrations.md`
### Common Patterns
```
1. Excel → Email: Read data → HTML table → send
2. OCR → Email: Recognize invoice → extract key info → send
3. PDF → Email: Process PDF → summary + attachment → send
4. Data Analysis → Email: Analyze data → conclusions → send
5. Scheduled Report: Generate content → schedule → send
```
### Excel Data → Email Example
```bash
# Step 1: Read and format data (use excel-studio or python3)
# Step 2: Save HTML content using a template from references/templates.md
# Step 3: Send
python3 scripts/send_mail.py \
--to "boss@company.com" \
--subject "Sales Report $(date +%Y%m%d)" \
--body-file "${OPENCLAW_WORKSPACE:-$PWD}/.emailbox_body.txt" \
--html-file "${OPENCLAW_WORKSPACE:-$PWD}/.emailbox_body.html" \
--attach "/path/to/report.xlsx" \
--provider qq
```
### Related Skills
| Skill | Integration | Scenario |
|-------|------------|----------|
| china-doc-ocr | OCR → email content | Invoice/contract recognition then email |
| excel-studio | Excel → table email | Data reports, financial statements |
| pdf-studio | PDF → email attachment | PDF report sending |
| data-analyzer | Analysis → email conclusions | Data insight notifications |
---
## Step 6: Schedule Email
### Send at Specific Time
```bash
python3 scripts/schedule_mail.py \
--schedule --at "2026-04-19 09:00" \
--to "boss@company.com" \
--subject "Daily Report - 2026-04-19" \
--body "Today's work summary..." \
--provider qq
```
### Send in N Minutes
```bash
python3 scripts/schedule_mail.py \
--schedule --in 30 \
--to "client@example.com" \
--subject "Follow up" \
--body "Following up on our meeting..." \
--provider 163
```
### Manage Scheduled Emails
```bash
# View scheduled emails
python3 scripts/schedule_mail.py --list-scheduled
# Cancel a scheduled email
python3 scripts/schedule_mail.py --cancel SCHEDULE_ID
# Manually process due emails
python3 scripts/schedule_mail.py --process-queue
```
### Auto-Processing (Manual Setup Only)
**⚠️ The schedule script will NEVER modify your crontab automatically.** You must manually confirm any crontab changes.
```bash
# Step 1: Check your current crontab first
crontab -l > ~/crontab_backup.txt
# Step 2: Add the emailbox processor manually (review before adding!)
# Add this line to your crontab ONLY if you want auto-processing:
# * * * * * python3 /path/to/emailbox/scripts/schedule_mail.py --process-queue
# Step 3: To remove later, edit your crontab and remove the line
```
---
## Step 7: HTML Email Templates
7 professional templates available → `references/templates.md`
| Template | Use Case |
|----------|----------|
| Business Report | Data reports, financial summaries |
| Meeting Invitation | Meetings, events, interviews |
| Notification / Announcement | Company announcements, system alerts |
| Thank You Letter | Appreciation, follow-ups |
| Weekly/Daily Report | Work progress updates |
| Invoice Notification | Invoice/receipt processing |
| Formal Letter | Official correspondence |
---
## Provider Configuration
12+ providers with IMAP/SMTP config and auth code guides → `references/providers.md`
| Provider | IMAP | SMTP | Port | Auth | China |
|----------|------|------|------|------|-------|
| QQ Mail | imap.qq.com | smtp.qq.com | 465 | Authorization code | Yes |
| 163 Mail | imap.163.com | smtp.163.com | 465 | Client password | Yes |
| 126 Mail | imap.126.com | smtp.126.com | 465 | Client password | Yes |
| Sina | imap.sina.com | smtp.sina.com | 465 | Enable IMAP | Yes |
| Outlook | outlook.office365.com | smtp.office365.com | 587 | App password | Yes |
| Gmail | imap.gmail.com | smtp.gmail.com | 587 | App password | VPN |
| Yahoo | imap.mail.yahoo.com | smtp.mail.yahoo.com | 587 | App password | VPN |
| iCloud | imap.mail.me.com | smtp.mail.me.com | 587 | App password | VPN |
| Tencent Exmail | imap.exmail.qq.com | smtp.exmail.qq.com | 465 | Enable IMAP | Yes |
| Ali Mail | imap.mxhichina.com | smtp.mxhichina.com | 465 | Enable IMAP | Yes |
| Huawei | imap.mail.hicloud.com | smtp.mail.hicloud.com | 465 | App password | Yes |
| 139 Mail | imap.mail.139.com | smtp.mail.139.com | 465 | Enable IMAP | Yes |
---
## Error Handling
```
Error → Solution
──────────────────────────────────────────────────────────
SMTP auth failed → Check authorization code, see providers.md
IMAP connection failed → Verify IMAP enabled, check network
Connection timeout → Gmail/Yahoo/iCloud need VPN in China
SMTP auth code error (QQ/163) → Use authorization code, NOT login password
Sending rate limit → QQ: 1/min, 500/day; 163: 200/day; Gmail: 500/day
Attachment too large → QQ: 50MB; Gmail: 25MB; Outlook: 20MB
IMAP not enabled → Enable in email settings, see providers.md
163 requires phone verification → Verify via SMS, wait 5-10 minutes
```
---
## Privacy & Security
- Direct IMAP/SMTP connection to email servers, no third-party data transfer
- **Credentials should be stored in environment variables only, NOT in plaintext files**
- ⚠️ 环境变量中的凭据可能通过 shell history、进程列表（`ps aux`）、CI 日志、崩溃报告泄露
- 用完授权码后建议 `unset EMAIL_AUTH` 清除当前 shell 的凭据
- Use provider-specific app passwords/authorization codes (NOT your login password)
- Authorization codes are email-specific, cannot be used to log into webmail
- Schedule queue stored in `~/.emailbox/queue/` — review and clean up regularly
- **This skill will NEVER modify your crontab or system scheduler without your explicit manual action**
- For maximum security, use a dedicated email account for automated sending
## Notes
- Requires IMAP/SMTP service enabled and authorization code configured
- Gmail/Yahoo/iCloud require VPN in mainland China
- QQ Mail limits: 500 emails/day, 1 email/minute
- 163/126 Mail limits: 200 emails/day
- Attachment size limits vary by provider (QQ: 50MB, Gmail: 25MB, Outlook: 20MB)
- Scheduled sending uses a local queue in `~/.emailbox/queue/`; processing requires manual crontab setup
- **Always use app passwords/authorization codes, never your real email login password**don't have the plugin yet? install it then click "run inline in claude" again.