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配置方式:

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:

{
  "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:发送带附件的周报邮件

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

执行成功输出:

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

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

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,解锁完整邮件自动化能力.