--- slug: "emailbox" source_type: "clawhub" source_url: "https://clawhub.ai/skills/emailbox" repo: "" source_file: "description" --- --- 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 "" \ --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 " \ --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 " \ --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**