email-skill

📧 Email Skill (Unified Entry Point)

This Skill is aunified email entry point：

• supports platform public mail service (platform)
• supports personal email IMAP/SMTP (personal)
• two methodscan coexist, and users can choose freely based on the scenario

---

1. Design Goals

email-skill As a unified orchestration layer:

• Unified Entry Point: expose all email capabilities through a single script
• Free Choice: users can choose based on the task platform or personal
• Capability Transparency: clearly show the capability boundaries and configuration costs of each method
• Coexistence and Compatibility: retain the original public mail process while seamlessly integrating imap-smtp-email
• Cross-platform: simultaneously support macOS/Linux (bash) and Windows (CMD)

---

2. Capability Overview

provider = platform(Platform Public Mail Service)

Positioning: the platform public mail is amessage push channel, specifically used to push content to the user's own mailbox. It is not a general-purpose email sending tool.

Features：

• No need to configure SMTP/IMAP hosts and passwords, ready to use out of the box
• Binding and sending are completed through the platform API
• ⚠️ Core limitation: only supports sending emails to the user's own mailbox. The binding process requires the user to log in to the target mailbox to receive a verification code, so the recipient can only be a mailbox the user has login access to, and emails cannot be sent to others
• Suitable scenarios:message push-type requirements, for example:
  • "Help me send today's weather forecast to my email"
  • "Push this analysis report to me"
  • "Send the daily summary to my email"
  • "Send this content to myself for keeping"

Capabilities：

• Check whether the mailbox is already bound
• Send a verification code to the target mailbox (the user needs to log in to that mailbox to view the verification code)
• Verify the verification code and bind the mailbox
• Send plain text emails to the bound user's own mailbox

Not supported：

• ❌ Cannot send emails to others(cannot send to colleagues, customers, or any third party)
• ❌ HTML email is not supported(the current public mail capability only provides plain text email,content_type must be text）
• ❌ Receiving/retrieving/attachment downloading is not supported
• ❌ Carbon copy (CC) and blind carbon copy (BCC) are not supported
• ❌ Attachment sending is not supported

💡 Simple judgment: if the user's requirement is "send some content to my own email", the public mail is suitable; if the requirement involves "sending to others", then it is not suitable, and personal。

provider = personal(Personal Email IMAP/SMTP)

Features：

• Use personal email credentials (.env configure IMAP/SMTP authorization code)
• Can send emails toany recipient, not subject to binding restrictions
• Supports complete email management capabilities: receiving, searching, downloading attachments, marking as read/unread
• Suitable scenarios: need to send emails to others, need inbox management, need complete email operation capabilities

Capabilities：

• SMTP sending (supports any recipient, CC, BCC, attachments)
• IMAP receiving/searching/reading details
• Attachment download, email status management, mailbox folder enumeration

---

3. How to choose a provider (Agent decision guidance)

⚠️ This section is for the Agent to understand and guide the user; it is not an executable command.

The Agent should, based on the user's actual needs, understand the intent through conversation and then guide the user to choose a suitable provider.Before the user chooses to use the public mailbox, the Agent must clearly explain the capability boundaries of the public mailbox to the user, let the user judge for themselves whether it is suitable, and then decide whether to use it.

Explanation of public mailbox capability boundaries (the Agent should proactively inform the user)

Before using the public mailbox, the Agent should convey the following key information to the user:

1. The public mailbox only supports sending emails to oneself: the recipient can only be the user's own mailbox with login permission, and it cannot be sent to anyone else
2. The public mailbox is essentially message push: suitable for pushing content (weather, reports, summaries, etc.) to the user's own mailbox, not a general-purpose email tool
3. The user decides whether to use it: after explaining the above limitations, the Agent should let the user judge for themselves whether the public mailbox meets their needs

Capability comparison：

Dimension	platform (public mailbox)	personal (personal mailbox)
Configuration cost	Zero configuration, ready to use out of the box	IMAP/SMTP credentials need to be configured
Recipient scope	Limited to the user's own mailbox	Any recipient
Typical use	Message push (weather/reports/reminders → yourself)	Email communication (send to colleagues/customers/anyone)
Sender identity	Platform unified sender	User's personal email address
Receiving capability	❌ Not supported	✅ Supported
Attachment sending	❌ Not supported	✅ Supported
CC/BCC	❌ Not supported	✅ Supported
Attachment download	❌ Not supported	✅ Supported

User intent signal → recommended provider：

• User says "push the weather/news/report to my mailbox" → platform(typical message push scenario)
• User says "send this content to myself" → platform
• User says "send an email to a colleague/customer" → personal(the public mailbox cannot send to others)
• User says "view/search/read emails" → personal
• User says "download email attachments" → personal
• User says "doesn't want to configure anything" → can recommend platform, butmust first inform that it can only be sent to oneself, with user confirmation
• User says "needs CC/BCC" → personal
• User says "needs to send with attachments" → personal
• User says "send email in HTML format" → personal(The platform public mailbox only supports plain text)

📌 Agent Code of Conduct: When the user's email-sending needs may be suitable for the platform public mailbox, the Agent should not make the decision directly on the user's behalf; it should first explain that "the platform public mailbox only supports sending emails to your own mailbox, and is mainly used for message push notifications," and execute only after the user confirms.

---

4. Unified entry script

macOS / Linux：scripts/unix/email_gateway.sh Windows：scripts\windows\email_gateway.cmd

4.1 View capabilities

macOS / Linux：

bash scripts/unix/email_gateway.sh capabilities

Windows CMD：

scripts\windows\email_gateway.cmd capabilities

4.2 Send email (unified send command)

Use the platform public mailbox

macOS / Linux：

bash scripts/unix/email_gateway.sh send \
  --provider platform \
  --email "user@example.com" \
  --subject "日报" \
  --body "今日汇总：项目A完成80%，项目B已提测。" \
  --content_type "text"

Windows CMD：

scripts\windows\email_gateway.cmd send --provider platform --email "user@example.com" --subject "日报" --body "今日汇总：项目A完成80%，项目B已提测。" --content_type "text"

Use personal mailbox SMTP

macOS / Linux：

bash scripts/unix/email_gateway.sh send \
  --provider personal \
  --to "user@example.com" \
  --subject "日报" \
  --body "今日汇总"

Windows CMD：

scripts\windows\email_gateway.cmd send --provider personal --to "user@example.com" --subject "日报" --body "今日汇总"

4.3 Platform public mailbox binding process

⚠️ Process constraint: Before the Agent uses the public mailbox to send email,it must first execute bind-check to check the binding status. If the returned result indicates that the mailbox is already bound, thendirectly execute the send, without going through the verification code process again. Only when the mailbox isnot bounddoes it need to execute step 2 (send verification code) and step 3 (verify binding).

macOS / Linux：

# 1) 检查绑定（必须先执行）
bash scripts/unix/email_gateway.sh bind-check --email "user@example.com"
# → 若已绑定：直接跳到 4.2 发送邮件，无需步骤 2、3
# → 若未绑定：继续执行步骤 2、3

# 2) 发送验证码（仅未绑定时执行，用户需登录该邮箱查看验证码）
bash scripts/unix/email_gateway.sh bind-send-code --email "user@example.com"

# 3) 验证绑定（仅未绑定时执行）
bash scripts/unix/email_gateway.sh bind-verify --email "user@example.com" --code "123456"

Windows CMD：

REM 1) 检查绑定（必须先执行）
scripts\windows\email_gateway.cmd bind-check --email "user@example.com"
REM → 若已绑定：直接跳到 4.2 发送邮件，无需步骤 2、3
REM → 若未绑定：继续执行步骤 2、3

REM 2) 发送验证码（仅未绑定时执行，用户需登录该邮箱查看验证码）
scripts\windows\email_gateway.cmd bind-send-code --email "user@example.com"

REM 3) 验证绑定（仅未绑定时执行）
scripts\windows\email_gateway.cmd bind-verify --email "user@example.com" --code "123456"

4.4 Personal mailbox capabilities (receiving/searching/attachments)

macOS / Linux：

# 检查邮件
bash scripts/unix/email_gateway.sh inbox-check --provider personal --limit 10 --recent 2h

# 搜索邮件
bash scripts/unix/email_gateway.sh inbox-search --provider personal --subject "发票" --unseen

# 拉取邮件详情
bash scripts/unix/email_gateway.sh inbox-fetch --provider personal 12345

# 下载附件
bash scripts/unix/email_gateway.sh inbox-download --provider personal 12345 --dir ~/Downloads

Windows CMD：

REM 检查邮件
scripts\windows\email_gateway.cmd inbox-check --provider personal --limit 10 --recent 2h

REM 搜索邮件
scripts\windows\email_gateway.cmd inbox-search --provider personal --subject "发票" --unseen

REM 拉取邮件详情
scripts\windows\email_gateway.cmd inbox-fetch --provider personal 12345

REM 下载附件
scripts\windows\email_gateway.cmd inbox-download --provider personal 12345 --dir %USERPROFILE%\Downloads

---

5. Configuration method

5.1 Platform public mailbox (platform)

• No SMTP/IMAP configuration required
• The local proxy must be available (the script forwards platform API requests through the proxy)
• Before the first send, execute bind-check to check the binding status: if already bound, you can send directly; if not bound, complete mailbox binding according to the binding process (the user must be able to log in to the target mailbox to receive the verification code)

5.2 Personal mailbox (personal)

1. Enter the imap-smtp-email directory
2. Install dependencies:npm install
3. Initialize configuration:

macOS / Linux：

bash scripts/unix/email_gateway.sh setup-personal

Windows CMD：

scripts\windows\email_gateway.cmd setup-personal

This wizard will generate imap-smtp-email/.env, including IMAP/SMTP host, account, authorization code, and other configuration.

---

6. Directory structure

email-skill/
├── SKILL.md
└── scripts/
    ├── unix/                         # macOS / Linux 脚本
    │   ├── email_gateway.sh          # 统一入口
    │   ├── common.sh                 # 公共函数库
    │   ├── check_bind.sh             # platform: 检查绑定
    │   ├── send_code.sh              # platform: 发送验证码
    │   ├── verify_bind.sh            # platform: 校验绑定
    │   └── send_email.sh             # platform: 发送邮件
    └── windows/                      # Windows CMD 脚本
        ├── email_gateway.cmd         # 统一入口
        ├── common.cmd                # 公共函数库
        ├── check_bind.cmd            # platform: 检查绑定
        ├── send_code.cmd             # platform: 发送验证码
        ├── verify_bind.cmd           # platform: 校验绑定
        └── send_email.cmd            # platform: 发送邮件

imap-smtp-email/
├── SKILL.md
├── setup.sh
└── scripts/
    ├── imap.js                       # personal: 收件/检索/附件
    └── smtp.js                       # personal: 发件

---

7. Compatibility and constraints

• The unified entry does not modify imap-smtp-email 's existing behavior, and only performs routing and orchestration
• provider=personal requires locally available node, and completes the .env configuration
• provider=platform Before sending, you must first execute bind-check to confirm the binding status:if already bound, send directly; only if not bound do you need to execute sending the verification code (bind-send-code) and binding (bind-verify) process
• All scripts depend on node and curl(Windows 10+ includes curl)
• macOS/Linux scripts preferentially use jq, and fall back to node

Prerequisites for scheduled email tasks

⚠️ Complete mailbox binding in advance: If the user needs to set up scheduled email tasks (such as daily scheduled weather push, weekly report summaries, etc.) and use platform public mailbox for push notifications, the Agent must, before creating the scheduled taskbeforehandguide the user to complete the mailbox verification and binding process (bind-check → bind-send-code → bind-verify). Because the user is not present when the scheduled task executes, real-time verification code interaction cannot be completed; if the mailbox is not bound in advance, the scheduled task will not be able to send email normally.

Exception fallback strategy

⚠️ Automatic switch when public mailbox sending quota is insufficient: Use platform When sending via the public mailbox (including sending verification codes and formal emails), if the API returns "The public domain has reached its daily sending limit" or another error indicating insufficient sending quota, it means the platform's public mailbox quota for the day has been exhausted. In this case, the Agent shouldautomatically switch to personal(personal mailbox SMTP) modeto help the user continue sending without manual intervention. Before switching, briefly explain the reason to the user (e.g., "The public mailbox quota for today has been used up, so it has automatically switched to your personal mailbox to send for you"). If personal mode has not been configured yet, the Agent should guide the user to complete the setup-personal configuration before sending.

Email encoding specification

⚠️ Prefer UTF-8 encoding: When sending emails via the public mailbox (using platform), the email subject and body content should preferably use UTF-8 encoding.