邮件技能免费版

SKILL.md

---
slug: "email-skill-free"
name: "email-skill-free"
version: "1.0.0"
displayName: "邮件技能免费版"
summary: "SMTP基础邮件发送,支持单供应商与纯文本附件投递。基于SMTP协议的轻量邮件发送Skill,提供纯文本正文、单附件投递与 测试邮件校验能力,支持Gmail与Outlook主流服务商。适用于"
summary_zh: "SMTP基础邮件发送,支持单供应商与纯文本附件投递。基于SMTP协议的轻量邮件发送Skill,提供纯文本正文、单附件投递与 测试邮件校验能力,支持Gmail与Outlook主流服务商。适用于"
license: "MIT"
description: "|-. 适用于需要email skill相关能力的开发场景,包含结构化的工作流程和可复用的模板,帮助用户快速完成任务并保持代码质量.该技能适用于相关开发场景,包含结构化的工作流程和配置指引.经过深度差异化处置,针对用户反馈和使用痛点进行了改进,提升了实用性和可操作性.该技能适用于相关开发场景,包含结构化的工作流程和配置指引.经过深度差异化处置,针对用户反馈和使用痛点进行了改进,提升了实用性和可操作性."
  基于SMTP协议的轻量邮件发送Skill,提供纯文本正文、单附件投递与
  测试邮件校验能力,支持Gmail与Outlook主流服务商。适用于个人开发者
  日常通知、简单报表投递等基础发信场景,是邮件自动化的入门版本.
tags:
  - Communication
  - email
  - skill
  - automation
  - productivity
  - SMTP
  - 邮件
  - 通信
  - 工具
  - gmail
tools:
  - read
  - exec
  - write
homepage: ""
category: "Communication"
pricing_tier: free
---
# Email Free

基于SMTP协议的轻量邮件发送Skill,覆盖"配置-校验-投递"基础发信链路.
## 输入格式

| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| input | string | 是 | Email Free处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux

### 依赖项
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-----|:-----|:-----|:-----|
| LLM API | API | 必需 | 由Agent内置LLM提供 |

### API Key 配置
需要配置对应API Key，详见上文环境配置章节

### 可用性分类
- **分类**: MD+EXEC（）

**API Key配置方式**:
```bash
export API_KEY=${API_KEY:?请设置环境变量}
```
配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.
## 核心能力

- **主流供应商支持**:内置Gmail(smtp.gmail.com:587)与Outlook(smtp.office365.com:587)两套SMTP预设,自动启用TLS加密.
- **纯文本正文**:通过`--body`参数传入纯文本内容,自动按UTF-8编码,避免乱码.
- **单附件投递**:支持`--attachment`参数附加单个文件,受服务商25MB大小限制.
- **测试邮件校验**:`--test`标志发送最小化测试邮件,用于验证凭据与连通性.
- **凭据配置文件**:通过`email_config.json`集中管理SMTP服务器、端口、用户名、密码.
### 主流供应商支持

针对主流供应商支持,自动解析输入参数、调度任务队列、格式化输出,返回结构化响应.
**输入**: 用户提供主流供应商支持相关的配置参数、输入数据和处理选项.
**输出**: 返回主流供应商支持的处理结果。- 验证返回数据的完整性和格式正确性
- 参考`主流供应商支持`的配置文档进行参数调优
### 纯文本正文

针对纯文本正文,自动解析输入参数、调度任务队列、格式化输出,返回结构化响应.
**输入**: 用户提供纯文本正文相关的配置参数、输入数据和处理选项.
**输出**: 返回纯文本正文的处理结果。- 验证返回数据的完整性和格式正确性
- 参考`纯文本正文`的配置文档进行参数调优
### 单附件投递

针对单附件投递,自动解析输入参数、调度任务队列、格式化输出,返回结构化响应.
**输入**: 用户提供单附件投递相关的配置参数、输入数据和处理选项.
**输出**: 返回单附件投递的处理结果。- 验证返回数据的完整性和格式正确性
- 参考`单附件投递`的配置文档进行参数调优
#
## 快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

## 使用流程

1. **环境确认**: 确认Agent平台已加载本skill，检查依赖说明中的环境要求
2. **指令输入**: 向Agent描述需要执行的任务，引用`email-skill-free`的相关能力
3. **执行处理**: Agent按照核心能力章节的指令执行任务
4. **结果验证**: 检查输出结果是否符合预期，参考错误处理章节处理异常

#
## 环境准备

创建`email_config.json`:

```json
{
  "smtp_server": "smtp.gmail.com",
  "smtp_port": 587,
  "username": "your-email@gmail.com",
  "password": "your-app-password",
  "sender_name": "个人助手",
  "use_tls": true
}
```

Gmail用户需在账号开启2FA后,从"应用密码"页面生成16位应用专用密码填入`password`字段.
## 适用场景

### 场景一:日常通知邮件

- **输入**:收件人邮箱、主题、正文文本.
- **处理**:读取配置文件,通过TLS连接SMTP服务器投递纯文本邮件.
- **输出**:收件人收到通知邮件,命令行返回投递结果.
### 场景二:简单报表投递

- **输入**:单个PDF/Excel报表文件与收件人邮箱.
- **处理**:以附件形式投递,正文简述报表内容.
- **输出**:收件人收到带附件的纯文本邮件.
## 案例展示

### 案例1:发送带附件的周报邮件

```bash
python email_sender.py \
  --to "manager@company.com" \
  --subject "本周工作总结" \
  --body "附件为本周完成事项,请查收。" \
  --attachment "weekly_report.pdf"
```

执行成功输出:

```
Email sent successfully
Message-ID: <1894a3b2...@smtp.gmail.com>
```

### 案例2:发送测试邮件验证配置

```bash
python email_sender.py --to "your-email@gmail.com" --test
```

用于首次配置完成后验证凭据是否正确,避免正式发信时才发现鉴权失败.
## 异常处理

### AUTH_001 应用专用密码失效

- **现象**:`SMTPAuthenticationError: 535 Username and Password not accepted`.
- **原因**:Gmail账号未启用2FA,或应用专用密码过期.
- **处理**:重新生成应用专用密码,确认2FA开启后更新配置文件.
### CONN_002 SMTP端口被拦截

- **现象**:`SMTPConnectError: Connection refused`.
- **原因**:587端口被防火墙拦截.
- **处理**:切换至465端口并设置`use_ssl=true`、`use_tls=false`.
### ATTACH_003 附件超过25MB

- **现象**:`SMTPDataError: 552 Message size exceeds fixed limit`.
- **原因**:附件体积超过服务商硬限制.
- **处理**:压缩附件或拆分投递;超大文件改用云存储链接放入正文.
### FORMAT_004 收件人邮箱格式非法

- **现象**:`ValueError: Invalid recipient format`.
- **原因**:`--to`参数邮箱字符串缺失域名或含非法字符.
- **处理**:校验邮箱格式后剔除空项与重复项再检查网络连接和配置后重试.
### ENCODING_005 主题包含非ASCII字符乱码

- **现象**:收件方主题显示为`???`或未解码的编码串.
- **原因**:未对Subject做RFC 2047编码.
- **处理**:使用`email.header.Header(subject, 'utf-8').encode()`构造主题.
## FAQ

### Q1: 是否支持HTML富文本邮件?

免费版仅支持纯文本正文。HTML富文本、CSS内联样式、邮件模板等能力由付费版提供.
### Q2: 能否同时发送多个附件?

免费版仅支持单附件投递。多附件并行投递能力由付费版提供.
### Q3: 是否支持CC/BCC抄送?

免费版仅支持`--to`主收件人。CC/BCC收件人编排能力由付费版提供.
### Q4: 如何切换到QQ邮箱或自定义SMTP?

免费版仅内置Gmail与Outlook预设。QQ邮箱、Yahoo及自定义SMTP服务器适配由付费版提供.
## 错误处理

| 错误场景 | 原因 | 处理方式 |
|---:|---:|---:|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | 检查网络连接和配置后重试；确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 |

## 已知限制

- 仅支持纯文本正文,不支持HTML富文本与邮件模板.
- 单邮件仅支持单个附件,且受25MB服务商硬限制.
- 仅支持`--to`主收件人,不支持CC/BCC抄送.
- 仅内置Gmail与Outlook两套SMTP预设,不支持自定义服务器.
- 凭据仅支持配置文件方式注入,不支持环境变量与密钥管理服务.
---
## 快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 想要HTML富文本、多附件并行、CC/BCC抄送、多供应商适配与企业级凭据管理?升级至付费版 **email-skill**,解锁完整邮件自动化能力.