Emailbox

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)

# 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

# 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.

# 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

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

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:

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

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

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:

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:

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)

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

python3 scripts/receive_mail.py --read 123 --provider qq

Download Attachments

python3 scripts/receive_mail.py --read 123 --download-attachment 123 \
  --save-dir "${OPENCLAW_WORKSPACE:-$PWD}/downloads"

---

Step 3: Search Email

# 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:

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

# 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

# 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

---

Step 6: Schedule Email

Send at Specific Time

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

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

# 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.

# 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

---

Provider Configuration

12+ providers with IMAP/SMTP config and auth code guides → references/providers.md

---

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