📧 IMAP邮件获取API文档

GET /api/health

检查API服务状态

响应示例:

{
  "success": true,
  "data": {
    "status": "ok",
    "message": "邮件API服务运行正常",
    "timestamp": "2024-01-01T12:00:00"
  }
}

POST /api/emails/fetch

获取邮箱中的邮件（默认最新5封）

请求参数:

请求示例:

{
  "server": "imap.gmail.com",
  "username": "user@gmail.com",
  "password": "app_password",
  "port": 993,
  "use_ssl": true,
  "mailbox": "INBOX",
  "limit": 5
}

成功响应示例:

{
  "success": true,
  "data": {
    "server": "imap.gmail.com",
    "username": "user@gmail.com",
    "mailbox": "INBOX",
    "total_emails": 5,
    "fetch_time": "2024-01-01T12:00:00",
    "emails": [
      {
        "subject": "邮件主题",
        "from": "sender@example.com",
        "from_parsed": [{"name": "发件人", "email": "sender@example.com"}],
        "to": "user@gmail.com",
        "date": "Mon, 1 Jan 2024 12:00:00 +0000",
        "date_parsed": "2024-01-01T12:00:00+00:00",
        "body_text": "邮件正文",
        "body_html": "
邮件正文
",
        "body_text_from_html": "邮件正文",
        "attachments": [],
        "has_attachments": false,
        "attachment_count": 0,
        "category": "general",
        "priority": "normal",
        "size_bytes": 1024
      }
    ]
  }
}

部分解析失败响应示例:

{
  "success": true,
  "data": {
    "server": "imap.gmail.com",
    "username": "user@gmail.com",
    "mailbox": "INBOX",
    "total_emails": 3,
    "fetch_time": "2024-01-01T12:00:00",
    "emails": [
      {
        "subject": "正常邮件",
        "from": "sender@example.com",
        "body_text": "正常邮件内容",
        "category": "general"
      },
      {
        "message_id": "123",
        "subject": "解析失败",
        "from": "未知",
        "to": [],
        "date": "",
        "body_text": "",
        "body_html": "",
        "attachments": [],
        "error": "email.errors.HeaderParseError: Invalid header format"
      }
    ],
    "parsing_summary": {
      "total_attempted": 5,
      "successful": 3,
      "failed": 2,
      "success_rate": "60%"
    }
  }
}

POST /api/emails/test-connection

测试邮箱服务器连接

请求参数:

与 /api/emails/fetch 相同，但不需要 limit 参数

响应示例:

{
  "success": true,
  "data": {
    "connected": true,
    "server": "imap.gmail.com",
    "folders": ["INBOX", "Sent", "Drafts"],
    "inbox_count": 150
  }
}

GET /api/emails/categories

获取支持的邮件分类列表

响应示例:

{
  "success": true,
  "data": {
    "categories": [
      {"id": "general", "name": "普通邮件", "description": "一般邮件"},
      {"id": "work", "name": "工作邮件", "description": "包含工作相关关键词的邮件"},
      {"id": "notification", "name": "通知邮件", "description": "系统通知和提醒邮件"},
      {"id": "spam", "name": "垃圾邮件", "description": "可能的垃圾邮件"}
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "用户名或密码错误",
    "details": "详细错误信息"
  }
}

📈 增强的邮件解析稳定性

• 多重FETCH策略：自动尝试多种IMAP FETCH命令格式，确保最大兼容性
• 智能错误恢复：当邮件解析失败时，返回基本信息而非完全失败
• 详细调试输出：提供完整的错误堆栈和处理步骤日志
• 串行处理模式：优化为更稳定的串行处理，避免IMAP连接冲突

支持的FETCH策略（按优先级）：

1. (RFC822) - 标准RFC822格式
2. (BODY.PEEK[]) - 只读模式获取邮件体
3. (BODY[]) - 获取完整邮件体
4. (RFC822.HEADER RFC822.TEXT) - 分别获取头部和正文

错误处理机制：

• 自动检测和处理异常IMAP响应
• 提供降级处理，确保部分邮件解析成功
• 详细的错误分类和诊断信息
• 支持多种字符编码检测和转换

常见问题解决方案

问题	可能原因	解决方案
"unexpected response"错误	IMAP服务器返回非标准响应	API会自动尝试多种FETCH策略，查看日志了解详细信息
邮件解析失败	邮件格式异常或编码问题	API会返回基本信息，包含错误详情
文件夹名显示异常	IMAP UTF-7编码问题	API已支持多种编码解析和备用方案
连接超时	网络问题或服务器负载	检查网络连接，使用test-connection接口诊断

当前版本：v2.1.0

发布日期：2024年12月

🔄 更新日志

版本	日期	主要更新
v2.1.0	2024-12	• 增强邮件解析稳定性 • 多重FETCH策略支持 • 智能错误恢复机制 • 详细调试和日志功能
v2.0.0	2024-11	• 专业级IMAP LIST解析 • UTF-7编码支持 • 文件夹名称解析优化 • 多编码兼容性
v1.0.0	2024-10	• 基础IMAP邮件获取功能 • RESTful API接口 • 邮件分类和解析 • 附件处理支持

🚀 即将推出的功能

• 邮件搜索和过滤功能
• 批量邮件操作支持
• 邮件发送功能
• WebSocket实时推送
• 邮件缓存和同步机制